fix(awserrors): attach Retry-After without duplicating the error text (#1244)

Joining a coded error with RetryAfter rendered the bare code on a second
line, so logged and stored reasons read "...: ServiceUnavailable
ServiceUnavailable". Add WithRetryAfter, which wraps the error and keeps
its text while ResolveRetryAfter and ResolveErrorDetail still resolve the
hint and the code. Use it for the seal-capability refusal and the
incomplete DescribeInstances and DescribeInstanceTypes fan-out errors.

.github/CODEOWNERS

@@ -6,10 +6,10 @@
 # Set the matching branch protection rule on `dev` and `main` to
 # "Require review from Code Owners" or this file is advisory only.
 
-# Network layer is governed by ADR-0006 invariant tests.
+# Network layer is governed by its invariant tests.
 # Changes here must respect those clauses
-# see spinifex/network/invariants/
-# docs/development/proposals/az-local-architecture/0006-spinifex-network-layer-contract.md
-/spinifex/network/          @joshsiv-mulga
-/spinifex/vpcd/             @joshsiv-mulga
-/spinifex/network/invariants/ @joshsiv-mulga
+# see spinifex/domains/network/invariants/
+# mulga docs/development/proposals/region-local-architecture/0006-spinifex-network-layer-contract.md (proposal, not accepted)
+/spinifex/domains/network/          @joshsiv-mulga
+/spinifex/runtime/roles/vpcd/ @joshsiv-mulga
+/spinifex/domains/network/invariants/ @joshsiv-mulga

.github/ISSUE_TEMPLATE/1-bug.yml

@@ -0,0 +1,59 @@
+name: Bug report
+description: Something is not working as it should.
+labels: ["bug"]
+body:
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      options:
+        - EC2 / instances
+        - EBS / volumes
+        - S3 / object store
+        - VPC / networking
+        - IAM / authentication
+        - EKS
+        - API gateway
+        - Web UI
+        - CLI / daemon
+        - Observability / telemetry
+        - Build / CI / packaging
+        - Documentation
+        - Other / not sure
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Spinifex version
+      description: Output of `spinifex --version`, or the commit SHA you are on.
+      placeholder: v1.0.0, or commit abc1234
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you saw, what you expected instead, and how to reproduce it.
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs and output
+      description: Relevant log lines, error messages or command output.
+      render: shell
+
+  - type: textarea
+    id: platform
+    attributes:
+      label: Platform
+      description: Where you are running it, and how you deployed it.
+      placeholder: |
+        OS: Debian 13
+        Kernel: 6.12
+        Arch: amd64
+        Deployment: single node, systemd

.github/ISSUE_TEMPLATE/2-feature.yml

@@ -0,0 +1,11 @@
+name: Feature request
+description: Suggest something new.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like to see?
+      description: What you are trying to do, and what stops you today.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/3-docs.yml

@@ -0,0 +1,20 @@
+name: Documentation
+description: Something in the docs is wrong, missing or unclear.
+labels: ["documentation"]
+body:
+  - type: input
+    id: location
+    attributes:
+      label: Where
+      description: Link to the page, or the path to the file in this repository.
+      placeholder: https://docs.mulgadc.com/..., or README.md
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What is wrong
+      description: What is inaccurate, missing or confusing, and what it should say instead.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://docs.mulgadc.com
+    about: Guides, configuration reference and API compatibility notes.

.github/actions/e2e-analyze/analyze.go

@@ -91,9 +91,12 @@ type SuiteReport struct {
 	Label     string // short name, e.g. "single"
 	Total     int
 	FailCount int
-	Root      *Failure    // nil if no failures
-	Cascades  []Failure   // everything else that failed in this suite
-	Buckets   [][]Failure // failures grouped by signature (root's bucket first)
+	// Unresolved counts testcases go-junit-report could not find an outcome
+	// for. They are not failures and the suite can be green with hundreds.
+	Unresolved int
+	Root       *Failure    // nil if no failures
+	Cascades   []Failure   // everything else that failed in this suite
+	Buckets    [][]Failure // failures grouped by signature (root's bucket first)
 	// EndedAt is go-junit-report's <testsuite timestamp>, which records when
 	// the XML was produced — i.e. when the suite finished, not when it began.
 	EndedAt time.Time
@@ -131,21 +134,22 @@ var cascadeMarkers = []string{
 	"Expected value not to be nil",
 }
 
-// teardownPatterns match the content a test logs from t.Cleanup or from the
-// harness's on-failure diagnostics — i.e. after it has already failed. They are
-// the LAST file:line lines in the failure body, so extractErrorLine's
-// keep-the-last rule picks them over the assertion unless they are skipped.
-// Anchored deliberately: a fragment loose enough to match an assertion would
-// blank out the one line the report exists to show.
-var teardownPatterns = []*regexp.Regexp{
+// nonFailurePatterns match content a test emits AFTER the assertion that failed
+// — t.Cleanup, harness diagnostics, or a t.Logf on a passing branch — which
+// extractErrorLine's keep-the-last rule would otherwise pick over the assertion.
+// Go emits t.Logf and t.Errorf identically, so anchor every entry: a fragment
+// loose enough to match an assertion blanks out the line the report exists to
+// show. `\bas expected\b` unanchored also matches "did not fail as expected".
+var nonFailurePatterns = []*regexp.Regexp{
 	regexp.MustCompile(`^DB instance \S+ is gone$`),
 	regexp.MustCompile(`^db diagnostics \S+:`),
+	regexp.MustCompile(`^\S+: management bridge \S+:\d+ refused as expected$`),
 }
 
-// isTeardownLine reports whether a candidate error line was emitted after the
-// failure it would otherwise be mistaken for.
-func isTeardownLine(content string) bool {
-	for _, re := range teardownPatterns {
+// isNonFailureLine reports whether a candidate error line was emitted after the
+// failure it would otherwise be mistaken for, or reports an expected outcome.
+func isNonFailureLine(content string) bool {
+	for _, re := range nonFailurePatterns {
 		if re.MatchString(content) {
 			return true
 		}
@@ -242,12 +246,12 @@ func extractErrorLine(body string) string {
 			// progress lines from the same file:line pattern before the
 			// failing assertion finally fires. Cleanup runs after it, though,
 			// so its lines are last of all and have to be skipped.
-			if content := strings.TrimSpace(m[1]); !isTeardownLine(content) {
+			if content := strings.TrimSpace(m[1]); !isNonFailureLine(content) {
 				goFileLine = content
 			}
 			continue
 		}
-		if fileHintRe.MatchString(l) && !isTeardownLine(l) {
+		if fileHintRe.MatchString(l) && !isNonFailureLine(l) {
 			lastTestLine = l
 		}
 	}
@@ -293,15 +297,23 @@ func extractFileHint(body string) string {
 	}
 	// Scanned line by line rather than across the body so a cleanup line's own
 	// file:line does not become the site the report points a reader at.
-	hint := ""
+	hint, filtered := "", ""
 	for _, raw := range strings.Split(body, "\n") {
 		l := strings.TrimSpace(raw)
-		if m := goFileLineRe.FindStringSubmatch(l); m != nil && isTeardownLine(strings.TrimSpace(m[1])) {
+		all := fileHintRe.FindAllString(l, -1)
+		if len(all) == 0 {
 			continue
 		}
-		if all := fileHintRe.FindAllString(l, -1); len(all) > 0 {
-			hint = all[len(all)-1]
+		if m := goFileLineRe.FindStringSubmatch(l); m != nil && isNonFailureLine(strings.TrimSpace(m[1])) {
+			filtered = all[len(all)-1]
+			continue
 		}
+		hint = all[len(all)-1]
+	}
+	// A body whose only file:line was allowlisted still gets a pointer: coarse
+	// beats none, and extractErrorLine has the same last-resort shape.
+	if hint == "" {
+		return filtered
 	}
 	return hint
 }
@@ -366,7 +378,7 @@ func computeLeafSet(cases []junitTC) map[string]bool {
 func computeRolledUpSet(cases []junitTC) map[string]bool {
 	rolledUp := make(map[string]bool, len(cases))
 	for _, tc := range cases {
-		if tc.Failure == nil && tc.Error == nil {
+		if tc.Failure == nil && !isRealError(tc.Error) {
 			continue
 		}
 		// Mark every ancestor: the failure belongs to the deepest case that
@@ -412,6 +424,18 @@ func parseStartTime(s string) time.Time {
 	return t
 }
 
+// noResultMessage is go-junit-report's marker for a testcase it saw start and
+// never saw finish. On cell-20 it accounted for 93 of the 120 testcases and 24
+// of the 25 reported failures, none of which had failed.
+const noResultMessage = "No test result found"
+
+// isRealError separates a genuine <error> from the parser's no-result marker.
+// A parent must not be treated as rolled up by a child whose outcome is merely
+// unknown, or the parent's own failure is dropped along with it.
+func isRealError(e *junitFailure) bool {
+	return e != nil && strings.TrimSpace(e.Message) != noResultMessage
+}
+
 // suiteLabel turns "junit-single.xml" into "single".
 func suiteLabel(path string) string {
 	base := filepath.Base(path)
@@ -457,6 +481,17 @@ func ParseFile(path string, data []byte) (SuiteReport, error) {
 			case tc.Failure != nil:
 				body = tc.Failure.Body
 			case tc.Error != nil:
+				// go-junit-report emits this when a `=== RUN` line has no
+				// matching result line. It means the outcome is unknown, not
+				// that the test errored, and it attaches the test's own log
+				// output — which then reads as an assertion.
+				if !isRealError(tc.Error) {
+					rep.Unresolved++
+					if leaf {
+						cumul += tc.Time
+					}
+					continue
+				}
 				body = tc.Error.Body
 			default:
 				if leaf {
@@ -553,6 +588,18 @@ func ParseFile(path string, data []byte) (SuiteReport, error) {
 }
 
 // Render writes the markdown report.
+// writeUnresolved names the testcases whose outcome the parser could not read.
+// Worth surfacing because a suite that leaves most of its subtests unresolved
+// is reporting on far less than its test count suggests.
+func writeUnresolved(b *strings.Builder, s SuiteReport) {
+	if s.Unresolved == 0 {
+		return
+	}
+	fmt.Fprintf(b, "ℹ️ %d of %d testcases have no result line in the log, so `go-junit-report` "+
+		"could not read their outcome. Not failures — but this suite reports on %d tests, not %d.\n\n",
+		s.Unresolved, s.Total, s.Total-s.Unresolved, s.Total)
+}
+
 func Render(r Report) string {
 	var b strings.Builder
 	fmt.Fprintf(&b, "## %s\n\n", r.Title)
@@ -579,9 +626,11 @@ func Render(r Report) string {
 	for _, s := range r.Suites {
 		if s.FailCount == 0 {
 			fmt.Fprintf(&b, "### Suite `%s`: ✅ pass (%d tests)\n\n", s.Label, s.Total)
+			writeUnresolved(&b, s)
 			continue
 		}
 		fmt.Fprintf(&b, "### Suite `%s`: %d failed, 1 root cause likely\n\n", s.Label, s.FailCount)
+		writeUnresolved(&b, s)
 
 		if s.Root != nil {
 			// XML order is completion order, so "earliest" only means earliest

.github/actions/e2e-analyze/analyze_test.go

@@ -141,6 +141,46 @@ func TestExtractErrorLine_SkipsCleanupLoggedAfterTheFailure(t *testing.T) {
 	}
 }
 
+// A subtest looping over two subjects calls t.Errorf for the first and t.Logf
+// for the second, so the success line is last in the body. Nightly run
+// 34383800404 reported that log line as the failure.
+func TestExtractErrorLine_SkipsSuccessLoggedAfterTheFailure(t *testing.T) {
+	body := `    isolation_test.go:80: rds-e2e-iso-a-1788981456: management bridge 10.15.8.10:5432 could not be tested: want connection refused, got dial tcp 10.15.8.10:5432: i/o timeout
+    isolation_test.go:84: rds-e2e-iso-b-1788981456: management bridge 10.15.8.11:5432 refused as expected`
+	got := extractErrorLine(body)
+	if !strings.Contains(got, "could not be tested") {
+		t.Errorf("extractErrorLine = %q, want the assertion at isolation_test.go:80", got)
+	}
+	if hint := extractFileHint(body); hint != "isolation_test.go:80" {
+		t.Errorf("extractFileHint = %q, want isolation_test.go:80", hint)
+	}
+}
+
+// "as expected" reads the same in an affirmation and in its negation, so an
+// unanchored pattern suppresses the assertion it was meant to outrank and
+// promotes a harness progress line in its place.
+func TestExtractErrorLine_KeepsNegatedExpectationAssertions(t *testing.T) {
+	body := `    isolation_test.go:60: waiting for the db instance to become available
+    isolation_test.go:80: rds-e2e-iso-a: management bridge 10.15.8.10:5432 was not refused as expected: got a connection`
+	got := extractErrorLine(body)
+	if !strings.Contains(got, "was not refused as expected") {
+		t.Errorf("extractErrorLine = %q, want the assertion at isolation_test.go:80", got)
+	}
+	if hint := extractFileHint(body); hint != "isolation_test.go:80" {
+		t.Errorf("extractFileHint = %q, want isolation_test.go:80", hint)
+	}
+}
+
+// Every candidate allowlisted leaves extractFileHint with nothing to return,
+// and unlike extractErrorLine it has no last-resort branch. A coarse pointer
+// beats sending the reader to no file at all.
+func TestExtractFileHint_FallsBackWhenEveryCandidateFiltered(t *testing.T) {
+	body := `    isolation_test.go:84: rds-e2e-iso-b: management bridge 10.15.8.11:5432 refused as expected`
+	if hint := extractFileHint(body); hint != "isolation_test.go:84" {
+		t.Errorf("extractFileHint = %q, want isolation_test.go:84", hint)
+	}
+}
+
 func TestExtractFileHint_PicksLastMatch(t *testing.T) {
 	body := "ec2helpers.go:50: setup\n    vpc_test.go:227: Eventually: condition not met"
 	got := extractFileHint(body)
@@ -174,6 +214,55 @@ func TestParseFile_SkipsEmptyParentFailure(t *testing.T) {
 	}
 }
 
+// go-junit-report emits <error message="No test result found"> for a `=== RUN`
+// with no matching result line, and attaches the test's own log output. On a
+// baremetal cell that was 93 of 120 testcases and 24 of 25 reported failures,
+// none of which had failed: "ALB internal: 20/20 successful" read as an error.
+func TestParseFile_NoResultFoundIsNotAFailure(t *testing.T) {
+	xml := []byte(`<?xml version="1.0"?>
+<testsuites><testsuite name="" tests="3" failures="1" errors="2">
+  <testcase name="TestLB/Internal_ALB" time="0.0"><error message="No test result found"><![CDATA[
+    lb_test.go:88: ALB internal: 20/20 successful, 2 unique
+]]></error></testcase>
+  <testcase name="TestLB/Internal_NLB" time="0.0"><error message="No test result found"></error></testcase>
+  <testcase name="TestX/RealFailure" time="0.5"><failure message="Failed"><![CDATA[
+    foo_test.go:10:
+        Messages: real assertion message
+]]></failure></testcase>
+</testsuite></testsuites>`)
+	sr, err := ParseFile("junit-x.xml", xml)
+	if err != nil {
+		t.Fatalf("ParseFile: %v", err)
+	}
+	if sr.FailCount != 1 {
+		t.Fatalf("FailCount = %d, want 1 (no-result entries are not failures)", sr.FailCount)
+	}
+	if sr.Unresolved != 2 {
+		t.Fatalf("Unresolved = %d, want 2", sr.Unresolved)
+	}
+	if sr.Root == nil || sr.Root.Name != "TestX/RealFailure" {
+		t.Fatalf("expected the real failure as root, got %+v", sr.Root)
+	}
+}
+
+// An <error> that is not the parser's no-result marker is a genuine error and
+// must still be reported.
+func TestParseFile_KeepsARealError(t *testing.T) {
+	xml := []byte(`<?xml version="1.0"?>
+<testsuites><testsuite name="" tests="1" failures="0" errors="1">
+  <testcase name="TestX" time="0.5"><error message="panic"><![CDATA[
+    foo_test.go:10: panic: runtime error: index out of range
+]]></error></testcase>
+</testsuite></testsuites>`)
+	sr, err := ParseFile("junit-x.xml", xml)
+	if err != nil {
+		t.Fatalf("ParseFile: %v", err)
+	}
+	if sr.FailCount != 1 || sr.Unresolved != 0 {
+		t.Fatalf("FailCount = %d, Unresolved = %d, want 1 and 0", sr.FailCount, sr.Unresolved)
+	}
+}
+
 func TestParseFile_SkipsParentRolledUpBySubtests(t *testing.T) {
 	// A parent that logs during cleanup gets a non-empty body, and a t.Log like
 	// "DB instance … is gone" — which passing tests emit too — reads exactly

.github/actions/junit-report/README.md

@@ -8,7 +8,7 @@ Actions job summary and emits one `::error` annotation per failed test case.
 ```yaml
 - name: Publish test summary
   if: always()
-  uses: ./spinifex/.github/actions/junit-report   # or your own checkout path
+  uses: $/.github/actions/junit-report
   with:
     junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
     title: "Go E2E results"

.github/assets/architecture.svg

@@ -27,7 +27,7 @@
 <line x1="510.0" y1="212.0" x2="510.0" y2="220.0" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.55" stroke-dasharray="2 4"/>
 <rect x="28.0" y="224.0" width="964.0" height="94.0" rx="13" fill="#EE4B12" fill-opacity="0.05" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.5"/>
 <text x="48.0" y="251.0" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#EE4B12" font-weight="700" text-anchor="start" letter-spacing="1.5">AWS GATEWAY</text>
-<text x="48.0" y="272.0" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">spinifex/services/awsgw · TLS termination · SigV4 verification · IAM policy eval · NATS routing</text>
+<text x="48.0" y="272.0" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">spinifex/runtime/roles/awsgw · TLS termination · SigV4 verification · IAM policy eval · NATS routing</text>
 <rect x="46.0" y="287.0" width="68.2" height="22.0" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
 <text x="80.1" y="301.9" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">TLS 1.3</text>
 <rect x="123.2" y="287.0" width="88.0" height="22.0" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>

.github/assets/design-architecture.svg

@@ -51,7 +51,7 @@
   <!-- ═══ AWS GATEWAY ════════════════════════════════════ -->
   <rect x="16" y="154" width="868" height="104" rx="8" fill="url(#gw-grad)" stroke="#DC2626" stroke-width="1.3" stroke-opacity="0.75"/>
   <text x="32" y="176" font-family="'SF Mono', ui-monospace, monospace" font-size="12" fill="#F87171" font-weight="700" letter-spacing="1">AWS GATEWAY · port 9999</text>
-  <text x="876" y="176" font-family="'SF Mono', ui-monospace, monospace" font-size="9" fill="#71717a" text-anchor="end">spinifex/services/awsgw/awsgw.go</text>
+  <text x="876" y="176" font-family="'SF Mono', ui-monospace, monospace" font-size="9" fill="#71717a" text-anchor="end">spinifex/runtime/roles/awsgw/awsgw.go</text>
 
   <!-- Two-column feature bullets -->
   <g font-family="'Segoe UI', sans-serif" font-size="10.5" fill="#f5f5f5">

.github/assets/diagrams/exoscale-single-node.svg

@@ -0,0 +1,79 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1020" height="836" viewBox="0 0 1020 836" role="img" aria-label="Spinifex on a single Exoscale instance: the instance sits on the zone&#x27;s public network with one interface, eth0, holding its own address and the default route. Manual Elastic IPs are delivered to eth0 and routed by the host into OVN through the spx-nat transit veth, and an Exoscale block storage volume backs /var/lib/spinifex.">
+<rect x="0" y="0" width="1020" height="836" rx="20" fill="#14181D" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="28" y="42" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#EE4B12" font-weight="600" text-anchor="start" letter-spacing="2.5">SPINIFEX ON EXOSCALE — SINGLE NODE</text>
+<text x="992" y="42" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#9AA1A8" font-weight="400" text-anchor="end">one instance · routed NAT · Elastic IPs</text>
+<text x="28" y="72" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="23" fill="#F5F3EE" font-weight="800" text-anchor="start">One Exoscale instance, single Spinifex node</text>
+<rect x="28" y="92" width="964" height="76" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="48" y="122" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">INTERNET</text>
+<text x="972" y="122" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">AWS SDKs, SSH and guest egress all arrive here</text>
+<rect x="46" y="126" width="260.0" height="22" rx="7" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="176.0" y="140.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">aws-cli / Terraform / boto3 → :9999</text>
+<rect x="315.0" y="126" width="171.6" height="22" rx="7" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="400.8" y="140.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">ssh → guest Elastic IP</text>
+<rect x="495.6" y="126" width="205.6" height="22" rx="7" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="598.4" y="140.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">guest egress ← same address</text>
+<line x1="510" y1="170" x2="510" y2="186" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.55" stroke-dasharray="2 4"/>
+<rect x="28" y="188" width="964" height="582" rx="16" fill="#EE4B12" fill-opacity="0.022" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.45" stroke-dasharray="6 5"/>
+<text x="50" y="218" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#EE4B12" font-weight="600" text-anchor="start" letter-spacing="2">EXOSCALE ZONE DE-FRA-1  ·  PUBLIC NETWORK 91.92.116.0/23</text>
+<text x="970" y="218" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="end">gateway 91.92.116.1 · security group open to all</text>
+<rect x="48" y="232" width="924" height="520" rx="14" fill="#EE4B12" fill-opacity="0.05" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.5"/>
+<text x="68" y="266" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="16" fill="#F5F3EE" font-weight="800" text-anchor="start">standard.huge</text>
+<text x="212" y="266" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="400" text-anchor="start">spinifex-node-01  ·  8 vCPU / 32 GiB  ·  Ubuntu 26.04</text>
+<text x="952" y="266" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">one host = one Spinifex region</text>
+<line x1="68" y1="282" x2="952" y2="282" stroke="#EE4B12" stroke-opacity="0.25" stroke-width="1"/>
+<rect x="68" y="298" width="434" height="108" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="88" y="328" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">eth0 — PUBLIC INTERFACE</text>
+<text x="482" y="328" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">the only NIC</text>
+<text x="88" y="356" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#F3F1EC" font-weight="400" text-anchor="start">91.92.116.250/23  ·  holds the default route</text>
+<text x="88" y="378" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">advertise IP · API :9999 · SSH · host masquerade</text>
+<rect x="518" y="298" width="434" height="108" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="538" y="328" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">ELASTIC IPs — MANUAL</text>
+<text x="932" y="328" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">attached to the instance</text>
+<text x="538" y="356" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#F3F1EC" font-weight="400" text-anchor="start">89.145.163.1/32  →  delivered to eth0</text>
+<text x="538" y="378" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">the host routes each /32 into OVN, never owns it</text>
+<line x1="735" y1="406" x2="735" y2="422" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.55" stroke-dasharray="2 4"/>
+<rect x="68" y="424" width="884" height="40" rx="11" fill="#1E242B" fill-opacity="1.0" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.45"/>
+<text x="88" y="449" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#EE4B12" font-weight="600" text-anchor="start">spx-nat-host ⇄ spx-nat-ovs</text>
+<text x="296" y="449" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#9AA1A8" font-weight="400" text-anchor="start">transit 100.127.0.0/24  ·  EIP/32 routed in  ·  masquerade out eth0 for the rest</text>
+<line x1="510" y1="464" x2="510" y2="480" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.55" stroke-dasharray="2 4"/>
+<rect x="68" y="482" width="884" height="100" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="88" y="512" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">SPINIFEX CONTROL PLANE</text>
+<text x="932" y="512" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">every service is one binary: spx service &lt;name&gt;</text>
+<rect x="86" y="530" width="93.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="132.5" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">awsgw :9999</text>
+<rect x="188.0" y="530" width="58.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="217.0" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">daemon</text>
+<rect x="255.0" y="530" width="44.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="277.0" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">vpcd</text>
+<rect x="308.0" y="530" width="44.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="330.0" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">NATS</text>
+<rect x="361.0" y="530" width="86.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="404.0" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">predastore</text>
+<rect x="456.0" y="530" width="86.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="499.0" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">viperblock</text>
+<rect x="551.0" y="530" width="79.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="590.5" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">northstar</text>
+<rect x="639.0" y="530" width="72.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="675.0" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">ui :3000</text>
+<text x="86" y="568" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">SigV4 in, NATS in the middle, QEMU/KVM (nested) · OVN/OVS · Predastore · Viperblock underneath</text>
+<line x1="248" y1="582" x2="248" y2="598" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.4" stroke-dasharray="2 4"/>
+<line x1="772" y1="582" x2="772" y2="598" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.4" stroke-dasharray="2 4"/>
+<rect x="68" y="600" width="532" height="130" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="88" y="630" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">TENANT VPCs — OVN br-int</text>
+<text x="580" y="630" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">geneve-local</text>
+<rect x="86" y="644" width="496" height="34" rx="9" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="100" y="666" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">vpc-a  172.31.0.0/16</text>
+<text x="300" y="666" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#9AA1A8" font-weight="400" text-anchor="start">i-…  172.31.0.4  →  89.145.163.1</text>
+<rect x="86" y="686" width="496" height="34" rx="9" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="100" y="708" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">vpc-b  10.0.0.0/16</text>
+<text x="300" y="708" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#9AA1A8" font-weight="400" text-anchor="start">i-…  10.0.1.9  ·  private, egress only</text>
+<rect x="616" y="600" width="336" height="130" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="636" y="630" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">BLOCK STORAGE VOLUME</text>
+<text x="932" y="630" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">256 GiB+</text>
+<text x="636" y="658" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">virtio-blk  →  /dev/vdb</text>
+<text x="636" y="680" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">/var/lib/spinifex</text>
+<text x="636" y="700" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="11.5" fill="#5B636C" font-weight="400" text-anchor="start">found by-id, defaults,nofail</text>
+<text x="636" y="718" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="11.5" fill="#5B636C" font-weight="400" text-anchor="start">viperblock · predastore · JetStream</text>
+<text x="28" y="796" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">A guest&#x27;s public address is a manual Exoscale Elastic IP, delivered to eth0 addressed to itself — no private/public pair to translate.</text>
+<text x="28" y="814" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">The host routes it into OVN, so inbound and outbound are the same address and the guest sees its private IP only.</text>
+</svg>

.github/assets/diagrams/exoscale-three-node.svg

@@ -0,0 +1,123 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1020" height="796" viewBox="0 0 1020 796" role="img" aria-label="Spinifex across three Exoscale instances in one zone, spread by an anti-affinity group. Each has a public eth0 carrying its own Elastic IPs, a private-network eth1 for the cluster mesh, its own block storage volume and its share of the guests. Geneve, NATS JetStream, predastore erasure coding and the OVN raft join them east-west over the private network. This topology is not yet tested.">
+<rect x="0" y="0" width="1020" height="796" rx="20" fill="#14181D" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="28" y="42" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#EE4B12" font-weight="600" text-anchor="start" letter-spacing="2.5">SPINIFEX ON EXOSCALE — THREE NODES</text>
+<text x="992" y="42" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#9AA1A8" font-weight="400" text-anchor="end">anti-affinity group · one zone · not yet tested</text>
+<text x="28" y="72" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="23" fill="#F5F3EE" font-weight="800" text-anchor="start">Three Exoscale instances, redundant multi-node install</text>
+<rect x="28" y="92" width="964" height="76" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="48" y="122" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">INTERNET</text>
+<text x="972" y="122" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">one endpoint, whichever node answers</text>
+<rect x="46" y="126" width="260.0" height="22" rx="7" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="176.0" y="140.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">aws-cli / Terraform / boto3 → :9999</text>
+<rect x="315.0" y="126" width="171.6" height="22" rx="7" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="400.8" y="140.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">ssh → guest Elastic IP</text>
+<rect x="495.6" y="126" width="205.6" height="22" rx="7" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="598.4" y="140.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">guest egress ← same address</text>
+<line x1="510" y1="170" x2="510" y2="186" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.55" stroke-dasharray="2 4"/>
+<rect x="28" y="188" width="964" height="440" rx="16" fill="#EE4B12" fill-opacity="0.022" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.45" stroke-dasharray="6 5"/>
+<text x="50" y="218" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#EE4B12" font-weight="600" text-anchor="start" letter-spacing="2">EXOSCALE ZONE DE-FRA-1  ·  PUBLIC NETWORK + PRIVATE NETWORK</text>
+<text x="970" y="218" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="end">one security group · one anti-affinity group</text>
+<rect x="48" y="232" width="300" height="380" rx="14" fill="#EE4B12" fill-opacity="0.05" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.5"/>
+<text x="64" y="260" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="14" fill="#F5F3EE" font-weight="800" text-anchor="start">spinifex-node-01</text>
+<text x="332" y="260" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="end">standard.huge</text>
+<line x1="64" y1="272" x2="332" y2="272" stroke="#EE4B12" stroke-opacity="0.25" stroke-width="1"/>
+<rect x="64" y="284" width="268" height="50" rx="10" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="78" y="305" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">eth0  91.92.116.250</text>
+<text x="78" y="323" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="start">public · default route · API</text>
+<rect x="64" y="342" width="268" height="50" rx="10" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="78" y="363" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">eth1  10.10.0.11</text>
+<text x="78" y="381" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="start">private network · mesh · advertise · encap</text>
+<rect x="64" y="400" width="268" height="50" rx="10" fill="#1E242B" fill-opacity="1.0" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.45"/>
+<text x="78" y="421" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#EE4B12" font-weight="600" text-anchor="start">EIP  89.145.163.1</text>
+<text x="78" y="439" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">→ eth0 · /32 via spx-nat-host</text>
+<rect x="64" y="462" width="51.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="89.5" y="476.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">awsgw</text>
+<rect x="124.0" y="462" width="57.6" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="152.8" y="476.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">daemon</text>
+<rect x="190.6" y="462" width="44.4" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="212.8" y="476.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">vpcd</text>
+<rect x="64" y="492" width="44.4" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="86.2" y="506.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">nats</text>
+<rect x="117.4" y="492" width="84.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="159.4" y="506.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">predastore</text>
+<rect x="210.4" y="492" width="84.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="252.4" y="506.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">viperblock</text>
+<rect x="64" y="526" width="268" height="34" rx="9" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="76" y="548" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">i-23d2…  172.31.0.4 → 89.145.163.1</text>
+<rect x="64" y="568" width="268" height="34" rx="9" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="76" y="590" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">volume /dev/vdb → /var/lib/spinifex</text>
+<rect x="360" y="232" width="300" height="380" rx="14" fill="#EE4B12" fill-opacity="0.05" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.5"/>
+<text x="376" y="260" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="14" fill="#F5F3EE" font-weight="800" text-anchor="start">spinifex-node-02</text>
+<text x="644" y="260" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="end">standard.huge</text>
+<line x1="376" y1="272" x2="644" y2="272" stroke="#EE4B12" stroke-opacity="0.25" stroke-width="1"/>
+<rect x="376" y="284" width="268" height="50" rx="10" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="390" y="305" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">eth0  91.92.117.14</text>
+<text x="390" y="323" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="start">public · default route · API</text>
+<rect x="376" y="342" width="268" height="50" rx="10" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="390" y="363" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">eth1  10.10.0.12</text>
+<text x="390" y="381" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="start">private network · mesh · advertise · encap</text>
+<rect x="376" y="400" width="268" height="50" rx="10" fill="#1E242B" fill-opacity="1.0" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.45"/>
+<text x="390" y="421" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#EE4B12" font-weight="600" text-anchor="start">EIP  89.145.160.107</text>
+<text x="390" y="439" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">→ eth0 · /32 via spx-nat-host</text>
+<rect x="376" y="462" width="51.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="401.5" y="476.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">awsgw</text>
+<rect x="436.0" y="462" width="57.6" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="464.8" y="476.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">daemon</text>
+<rect x="502.6" y="462" width="44.4" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="524.8" y="476.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">vpcd</text>
+<rect x="376" y="492" width="44.4" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="398.2" y="506.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">nats</text>
+<rect x="429.4" y="492" width="84.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="471.4" y="506.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">predastore</text>
+<rect x="522.4" y="492" width="84.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="564.4" y="506.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">viperblock</text>
+<rect x="376" y="526" width="268" height="34" rx="9" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="388" y="548" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">i-6b91…  172.31.0.9 → 89.145.160.107</text>
+<rect x="376" y="568" width="268" height="34" rx="9" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="388" y="590" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">volume /dev/vdb → /var/lib/spinifex</text>
+<rect x="672" y="232" width="300" height="380" rx="14" fill="#EE4B12" fill-opacity="0.05" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.5"/>
+<text x="688" y="260" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="14" fill="#F5F3EE" font-weight="800" text-anchor="start">spinifex-node-03</text>
+<text x="956" y="260" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="end">standard.huge</text>
+<line x1="688" y1="272" x2="956" y2="272" stroke="#EE4B12" stroke-opacity="0.25" stroke-width="1"/>
+<rect x="688" y="284" width="268" height="50" rx="10" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="702" y="305" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">eth0  91.92.116.88</text>
+<text x="702" y="323" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="start">public · default route · API</text>
+<rect x="688" y="342" width="268" height="50" rx="10" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="702" y="363" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">eth1  10.10.0.13</text>
+<text x="702" y="381" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="start">private network · mesh · advertise · encap</text>
+<rect x="688" y="400" width="268" height="50" rx="10" fill="#1E242B" fill-opacity="1.0" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.45"/>
+<text x="702" y="421" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#EE4B12" font-weight="600" text-anchor="start">EIP  89.145.162.131</text>
+<text x="702" y="439" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">→ eth0 · /32 via spx-nat-host</text>
+<rect x="688" y="462" width="51.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="713.5" y="476.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">awsgw</text>
+<rect x="748.0" y="462" width="57.6" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="776.8" y="476.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">daemon</text>
+<rect x="814.6" y="462" width="44.4" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="836.8" y="476.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">vpcd</text>
+<rect x="688" y="492" width="44.4" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="710.2" y="506.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">nats</text>
+<rect x="741.4" y="492" width="84.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="783.4" y="506.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">predastore</text>
+<rect x="834.4" y="492" width="84.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="876.4" y="506.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle">viperblock</text>
+<rect x="688" y="526" width="268" height="34" rx="9" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="700" y="548" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">i-0ae4…  172.31.1.6 → 89.145.162.131</text>
+<rect x="688" y="568" width="268" height="34" rx="9" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="700" y="590" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">volume /dev/vdb → /var/lib/spinifex</text>
+<line x1="510" y1="628" x2="510" y2="644" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.55" stroke-dasharray="2 4"/>
+<rect x="28" y="646" width="964" height="70" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="48" y="676" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">EAST–WEST, OVER THE EXOSCALE PRIVATE NETWORK</text>
+<text x="972" y="676" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">no Elastic IP is involved · MTU 1500</text>
+<rect x="46" y="684" width="124.0" height="22" rx="7" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="108.0" y="698.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">Geneve UDP 6081</text>
+<rect x="179.0" y="684" width="137.6" height="22" rx="7" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="247.8" y="698.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">NATS JetStream R3</text>
+<rect x="325.6" y="684" width="144.4" height="22" rx="7" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="397.8" y="698.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">predastore RS(2,1)</text>
+<rect x="479.0" y="684" width="151.2" height="22" rx="7" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="554.6" y="698.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">OVN Northbound raft</text>
+<rect x="639.2" y="684" width="56.0" height="22" rx="7" fill="none" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="667.2" y="698.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">OVSDB</text>
+<text x="28" y="744" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">Guest-to-guest traffic rides Geneve between the nodes&#x27; private-network interfaces — it never touches eth0 or an Elastic IP.</text>
+<text x="28" y="762" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">Each node carries the Elastic IPs of its own guests. Moving one between nodes is an Exoscale API call, not yet automated.</text>
+<text x="28" y="780" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">Three nodes is the smallest cluster that tolerates losing one; the anti-affinity group keeps them on different hypervisors.</text>
+</svg>

.github/assets/diagrams/oci-single-node.svg

@@ -0,0 +1,80 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1020" height="836" viewBox="0 0 1020 836" role="img" aria-label="Spinifex on a single OCI instance: the instance sits inside the VCN public subnet 10.200.0.0/23; its primary VNIC carries the default route and the cluster mesh, its secondary VNIC is the br-wan bridge holding registered secondary private IPs paired with reserved public IPs; guests reach them through the spx-nat transit veth, and an iSCSI block volume backs /var/lib/spinifex.">
+<defs><linearGradient id="nats" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#F5652E"/><stop offset="1" stop-color="#C63C0E"/></linearGradient></defs>
+<rect x="0" y="0" width="1020" height="836" rx="20" fill="#14181D" stroke="#2A2F36" stroke-width="1"/>
+<text x="28" y="42" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#EE4B12" font-weight="600" text-anchor="start" letter-spacing="2.5">SPINIFEX ON OCI — SINGLE NODE</text>
+<text x="992" y="42" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#9AA1A8" font-weight="400" text-anchor="end">one instance · routed NAT · real public addresses</text>
+<text x="28" y="72" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="23" fill="#F5F3EE" font-weight="800" text-anchor="start">One OCI instance, single Spinifex node</text>
+<rect x="28" y="92" width="964" height="76" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="48" y="122" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">INTERNET</text>
+<text x="972" y="122" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">AWS SDKs, SSH and guest egress all arrive here</text>
+<rect x="46" y="126" width="272.7" height="22" rx="7" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="182.3" y="140.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">aws-cli / Terraform / boto3 → :9999</text>
+<rect x="327.7" y="126" width="177.2" height="22" rx="7" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="416.3" y="140.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">ssh → guest public IP</text>
+<rect x="513.92" y="126" width="218.1" height="22" rx="7" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="623.0" y="140.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">guest egress ← same address</text>
+<line x1="510.0" y1="170" x2="510.0" y2="186" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.55" stroke-dasharray="2 4"/>
+<rect x="28" y="188" width="964" height="582" rx="16" fill="#EE4B12" fill-opacity="0.022" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.45" stroke-dasharray="6 5"/>
+<text x="50" y="218" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#EE4B12" font-weight="600" text-anchor="start" letter-spacing="2">OCI VCN 10.200.0.0/16  ·  PUBLIC SUBNET 10.200.0.0/23</text>
+<text x="970" y="218" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="end">virtual router 10.200.0.1 · internet gateway</text>
+<rect x="48" y="232" width="924" height="520" rx="14" fill="#EE4B12" fill-opacity="0.05" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.5"/>
+<text x="68" y="266" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="16" fill="#F5F3EE" font-weight="800" text-anchor="start">BM.Standard.E2.64</text>
+<text x="260" y="266" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="400" text-anchor="start">spinifex-node-01  ·  FAULT-DOMAIN-1</text>
+<text x="952" y="266" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">one host = one Spinifex region</text>
+<line x1="68" y1="282" x2="952" y2="282" stroke="#EE4B12" stroke-opacity="0.25" stroke-width="1"/>
+<rect x="68" y="298" width="434.0" height="108" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="88" y="328" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">VNIC 0 — PRIMARY</text>
+<text x="482.0" y="328" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">enp0s9</text>
+<text x="88" y="356" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#F3F1EC" font-weight="400" text-anchor="start">10.200.0.252/23  ·  holds the default route</text>
+<text x="88" y="378" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">advertise IP · ovn-encap-ip · NATS · API :9999</text>
+<rect x="518.0" y="298" width="434.0" height="108" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="538.0" y="328" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">VNIC 1 — SECONDARY</text>
+<text x="932.0" y="328" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">br-wan (Linux bridge)</text>
+<text x="538.0" y="356" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#F3F1EC" font-weight="400" text-anchor="start">10.200.1.233/32  +  ip rule → table 200</text>
+<text x="538.0" y="378" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">secondary private IPs ⇄ reserved public IPs</text>
+<line x1="735.0" y1="406" x2="735.0" y2="422" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.55" stroke-dasharray="2 4"/>
+<rect x="68" y="424" width="884" height="40" rx="11" fill="#1E242B" fill-opacity="1.0" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.45"/>
+<text x="88" y="449" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#EE4B12" font-weight="600" text-anchor="start">spx-nat-host ⇄ spx-nat-ovs</text>
+<text x="296" y="449" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#9AA1A8" font-weight="400" text-anchor="start">transit 100.127.0.0/24  ·  nft chain spinifex-nat-egress masquerades out br-wan</text>
+<line x1="510.0" y1="464" x2="510.0" y2="480" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.55" stroke-dasharray="2 4"/>
+<rect x="68" y="482" width="884" height="100" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="88" y="512" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">SPINIFEX CONTROL PLANE</text>
+<text x="932" y="512" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">every service is one binary: spx service &lt;name&gt;</text>
+<rect x="86" y="530" width="109.0" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="140.5" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">awsgw :9999</text>
+<rect x="204.01999999999998" y="530" width="74.9" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="241.5" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">daemon</text>
+<rect x="287.94" y="530" width="61.3" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="318.6" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">vpcd</text>
+<rect x="358.22" y="530" width="61.3" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="388.9" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">NATS</text>
+<rect x="428.5" y="530" width="102.2" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="479.6" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">predastore</text>
+<rect x="539.7" y="530" width="102.2" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="590.8" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">viperblock</text>
+<rect x="650.9000000000001" y="530" width="95.4" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="698.6" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">northstar</text>
+<rect x="755.2800000000001" y="530" width="88.6" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="799.6" y="544.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">ui :3000</text>
+<text x="86" y="568" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">SigV4 in, NATS in the middle, QEMU/KVM · OVN/OVS · Predastore · Viperblock underneath</text>
+<line x1="248" y1="582" x2="248" y2="598" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.4" stroke-dasharray="2 4"/>
+<line x1="772" y1="582" x2="772" y2="598" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.4" stroke-dasharray="2 4"/>
+<rect x="68" y="600" width="532" height="130" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="88" y="630" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">TENANT VPCs — OVN br-int</text>
+<text x="580" y="630" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">geneve-local</text>
+<rect x="86" y="644" width="496" height="34" rx="9" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="100" y="666" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">vpc-a  10.0.0.0/16</text>
+<text x="310" y="666" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#9AA1A8" font-weight="400" text-anchor="start">i-…  10.0.1.4  →  150.230.13.131</text>
+<rect x="86" y="686" width="496" height="34" rx="9" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="100" y="708" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">vpc-b  172.31.0.0/16</text>
+<text x="310" y="708" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#9AA1A8" font-weight="400" text-anchor="start">i-…  172.31.4.9  ·  private, egress only</text>
+<rect x="616" y="600" width="336" height="130" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="636" y="630" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">BLOCK VOLUME — iSCSI</text>
+<text x="932" y="630" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">256 GB+</text>
+<text x="636" y="658" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">169.254.2.2:3260  →  /dev/sdb</text>
+<text x="636" y="680" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">/var/lib/spinifex</text>
+<text x="636" y="700" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="11.5" fill="#5B636C" font-weight="400" text-anchor="start">mounted by UUID, defaults,_netdev,nofail</text>
+<text x="636" y="718" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="11.5" fill="#5B636C" font-weight="400" text-anchor="start">viperblock · predastore · JetStream</text>
+<text x="28" y="796" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">A guest's public address is a real OCI reserved public IP, attached to a secondary private IP on br-wan.</text>
+<text x="28" y="814" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">Inbound and outbound are therefore the same address, and OCI's per-VNIC source check passes.</text>
+</svg>

.github/assets/diagrams/oci-three-node.svg

@@ -0,0 +1,116 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1020" height="796" viewBox="0 0 1020 796" role="img" aria-label="Spinifex across three OCI instances: all three sit inside the VCN public subnet 10.200.0.0/23, one per fault domain. Each carries a primary VNIC for the cluster mesh and a br-wan secondary VNIC holding its reserved public addresses, its own iSCSI block volume, and its share of the guests. Geneve, NATS JetStream, predastore erasure coding and the OVN raft join them east-west.">
+<defs><linearGradient id="nats" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#F5652E"/><stop offset="1" stop-color="#C63C0E"/></linearGradient></defs>
+<rect x="0" y="0" width="1020" height="796" rx="20" fill="#14181D" stroke="#2A2F36" stroke-width="1"/>
+<text x="28" y="42" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#EE4B12" font-weight="600" text-anchor="start" letter-spacing="2.5">SPINIFEX ON OCI — THREE NODES</text>
+<text x="992" y="42" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#9AA1A8" font-weight="400" text-anchor="end">three fault domains · one region · one API endpoint</text>
+<text x="28" y="72" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="23" fill="#F5F3EE" font-weight="800" text-anchor="start">Three OCI instances, redundant multi-node install</text>
+<rect x="28" y="92" width="964" height="76" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="48" y="122" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">INTERNET</text>
+<text x="972" y="122" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">one endpoint, whichever node answers</text>
+<rect x="46" y="126" width="272.7" height="22" rx="7" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="182.3" y="140.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">aws-cli / Terraform / boto3 → :9999</text>
+<rect x="327.7" y="126" width="177.2" height="22" rx="7" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="416.3" y="140.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">ssh → guest public IP</text>
+<rect x="513.92" y="126" width="218.1" height="22" rx="7" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="623.0" y="140.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#9AA1A8" font-weight="400" text-anchor="middle">guest egress ← same address</text>
+<line x1="510.0" y1="170" x2="510.0" y2="186" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.55" stroke-dasharray="2 4"/>
+<rect x="28" y="188" width="964" height="464" rx="16" fill="#EE4B12" fill-opacity="0.022" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.45" stroke-dasharray="6 5"/>
+<text x="50" y="218" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#EE4B12" font-weight="600" text-anchor="start" letter-spacing="2">OCI VCN 10.200.0.0/16  ·  PUBLIC SUBNET 10.200.0.0/23</text>
+<text x="970" y="218" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="end">virtual router 10.200.0.1 · internet gateway</text>
+<rect x="48.0" y="232" width="297.3" height="272" rx="13" fill="#EE4B12" fill-opacity="0.05" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.5"/>
+<text x="66.0" y="262" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="14" fill="#F5F3EE" font-weight="800" text-anchor="start">spinifex-node-01</text>
+<text x="327.3333333333333" y="262" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#EE4B12" font-weight="400" text-anchor="end" fill-opacity="0.85">FAULT-DOMAIN-1</text>
+<text x="66.0" y="280" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="start">BM.Standard.E2.64</text>
+<line x1="66.0" y1="292" x2="327.3333333333333" y2="292" stroke="#EE4B12" stroke-opacity="0.25" stroke-width="1"/>
+<text x="66.0" y="314" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">VNIC 0  10.200.0.252</text>
+<text x="66.0" y="330" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="11" fill="#5B636C" font-weight="400" text-anchor="start">mesh · advertise · encap</text>
+<text x="66.0" y="352" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">VNIC 1  br-wan  10.200.1.233/32</text>
+<text x="66.0" y="368" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="11" fill="#5B636C" font-weight="400" text-anchor="start">public IP pairs · table 200</text>
+<rect x="66.0" y="382" width="51.0" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="91.5" y="394.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">awsgw</text>
+<rect x="123.0" y="382" width="57.2" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="151.6" y="394.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">daemon</text>
+<rect x="186.2" y="382" width="44.8" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="208.6" y="394.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">vpcd</text>
+<rect x="66.0" y="408" width="44.8" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="88.4" y="420.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">nats</text>
+<rect x="116.8" y="408" width="82.0" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="157.8" y="420.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">predastore</text>
+<rect x="204.8" y="408" width="82.0" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="245.8" y="420.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">viperblock</text>
+<rect x="66.0" y="438" width="261.3" height="24" rx="8" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="76.0" y="454" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">i-23d2…  10.0.1.4 → 150.230.13.131</text>
+<rect x="66.0" y="466" width="261.3" height="24" rx="8" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="76.0" y="482" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">iSCSI /dev/sdb → /var/lib/spinifex</text>
+<line x1="345.3333333333333" y1="364" x2="361.3333333333333" y2="364" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.5" stroke-dasharray="2 4"/>
+<rect x="361.3333333333333" y="232" width="297.3" height="272" rx="13" fill="#EE4B12" fill-opacity="0.05" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.5"/>
+<text x="379.3333333333333" y="262" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="14" fill="#F5F3EE" font-weight="800" text-anchor="start">spinifex-node-02</text>
+<text x="640.6666666666666" y="262" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#EE4B12" font-weight="400" text-anchor="end" fill-opacity="0.85">FAULT-DOMAIN-2</text>
+<text x="379.3333333333333" y="280" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="start">BM.Standard.E2.64</text>
+<line x1="379.3333333333333" y1="292" x2="640.6666666666666" y2="292" stroke="#EE4B12" stroke-opacity="0.25" stroke-width="1"/>
+<text x="379.3333333333333" y="314" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">VNIC 0  10.200.0.118</text>
+<text x="379.3333333333333" y="330" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="11" fill="#5B636C" font-weight="400" text-anchor="start">mesh · advertise · encap</text>
+<text x="379.3333333333333" y="352" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">VNIC 1  br-wan  10.200.1.96/32</text>
+<text x="379.3333333333333" y="368" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="11" fill="#5B636C" font-weight="400" text-anchor="start">public IP pairs · table 200</text>
+<rect x="379.3333333333333" y="382" width="51.0" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="404.8" y="394.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">awsgw</text>
+<rect x="436.3333333333333" y="382" width="57.2" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="464.9" y="394.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">daemon</text>
+<rect x="499.5333333333333" y="382" width="44.8" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="521.9" y="394.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">vpcd</text>
+<rect x="379.3333333333333" y="408" width="44.8" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="401.7" y="420.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">nats</text>
+<rect x="430.1333333333333" y="408" width="82.0" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="471.1" y="420.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">predastore</text>
+<rect x="518.1333333333333" y="408" width="82.0" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="559.1" y="420.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">viperblock</text>
+<rect x="379.3333333333333" y="438" width="261.3" height="24" rx="8" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="389.3333333333333" y="454" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">i-6b91…  10.0.1.9 → 137.23.9.125</text>
+<rect x="379.3333333333333" y="466" width="261.3" height="24" rx="8" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="389.3333333333333" y="482" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">iSCSI /dev/sdb → /var/lib/spinifex</text>
+<line x1="658.6666666666666" y1="364" x2="674.6666666666666" y2="364" stroke="#EE4B12" stroke-width="1.3" stroke-opacity="0.5" stroke-dasharray="2 4"/>
+<rect x="674.6666666666666" y="232" width="297.3" height="272" rx="13" fill="#EE4B12" fill-opacity="0.05" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.5"/>
+<text x="692.6666666666666" y="262" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="14" fill="#F5F3EE" font-weight="800" text-anchor="start">spinifex-node-03</text>
+<text x="954.0" y="262" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#EE4B12" font-weight="400" text-anchor="end" fill-opacity="0.85">FAULT-DOMAIN-3</text>
+<text x="692.6666666666666" y="280" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="start">BM.Standard.E2.64</text>
+<line x1="692.6666666666666" y1="292" x2="954.0" y2="292" stroke="#EE4B12" stroke-opacity="0.25" stroke-width="1"/>
+<text x="692.6666666666666" y="314" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">VNIC 0  10.200.0.41</text>
+<text x="692.6666666666666" y="330" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="11" fill="#5B636C" font-weight="400" text-anchor="start">mesh · advertise · encap</text>
+<text x="692.6666666666666" y="352" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11.5" fill="#F3F1EC" font-weight="400" text-anchor="start">VNIC 1  br-wan  10.200.1.12/32</text>
+<text x="692.6666666666666" y="368" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="11" fill="#5B636C" font-weight="400" text-anchor="start">public IP pairs · table 200</text>
+<rect x="692.6666666666666" y="382" width="51.0" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="718.2" y="394.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">awsgw</text>
+<rect x="749.6666666666666" y="382" width="57.2" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="778.3" y="394.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">daemon</text>
+<rect x="812.8666666666667" y="382" width="44.8" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="835.3" y="394.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">vpcd</text>
+<rect x="692.6666666666666" y="408" width="44.8" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="715.1" y="420.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">nats</text>
+<rect x="743.4666666666666" y="408" width="82.0" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="784.5" y="420.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">predastore</text>
+<rect x="831.4666666666666" y="408" width="82.0" height="20" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="872.5" y="420.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">viperblock</text>
+<rect x="692.6666666666666" y="438" width="261.3" height="24" rx="8" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="702.6666666666666" y="454" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">i-0ae4…  10.0.2.6 → 150.230.4.88</text>
+<rect x="692.6666666666666" y="466" width="261.3" height="24" rx="8" fill="none" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="702.6666666666666" y="482" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#9AA1A8" font-weight="400" text-anchor="start">iSCSI /dev/sdb → /var/lib/spinifex</text>
+<rect x="48" y="524" width="924" height="104" rx="13" fill="#181D23" fill-opacity="1.0" stroke="#2A2F36" stroke-width="1" stroke-opacity="1.0"/>
+<text x="68" y="554" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="12" fill="#9AA1A8" font-weight="700" text-anchor="start" letter-spacing="1.5">EAST–WEST, INSIDE THE VCN</text>
+<text x="952" y="554" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="10.5" fill="#5B636C" font-weight="400" text-anchor="end">no public address is involved</text>
+<rect x="66" y="574" width="136.3" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="134.2" y="588.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">Geneve UDP 6081</text>
+<rect x="211.3" y="574" width="149.9" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="286.3" y="588.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">NATS JetStream R3</text>
+<rect x="370.24" y="574" width="156.8" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="448.6" y="588.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">predastore RS(2,1)</text>
+<rect x="536.0" y="574" width="163.6" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="617.8" y="588.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">OVN Northbound raft</text>
+<rect x="708.58" y="574" width="68.1" height="22" rx="7" fill="#EE4B12" fill-opacity="0.06" stroke="#EE4B12" stroke-width="1" stroke-opacity="0.5"/>
+<text x="742.6" y="588.8" font-family="ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace" font-size="11" fill="#F3F1EC" font-weight="400" text-anchor="middle" fill-opacity="0.9">OVSDB</text>
+<text x="66" y="612" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">Guest-to-guest traffic rides Geneve between the nodes' primary VNICs — it never leaves the subnet and never touches br-wan.</text>
+<rect x="28" y="668" width="964" height="46" rx="12" fill="#EE4B12" fill-opacity="0.07" stroke="#EE4B12" stroke-width="1.4" stroke-opacity="0.55"/>
+<text x="48" y="688" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="13" fill="#F5F3EE" font-weight="700" text-anchor="start">A guest that moves takes its address with it.</text>
+<text x="48" y="705" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#9AA1A8" font-weight="400" text-anchor="start">The reserved public IP follows the secondary private IP to whichever node's br-wan the guest lands on — the tenant sees no change.</text>
+<text x="28" y="756" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">Three nodes is the smallest cluster that tolerates losing one: NATS JetStream keeps quorum, predastore RS(2,1)</text>
+<text x="28" y="774" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif" font-size="12" fill="#5B636C" font-weight="400" text-anchor="start">keeps the data readable, and the OVN Northbound raft keeps a leader. One node per fault domain is what makes that real.</text>
+</svg>

.github/assets/images/cisco-ucs-platform-benchmark/guest-storage-throughput.svg

@@ -0,0 +1,44 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="470" viewBox="0 0 760 470" font-family="-apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif">
+<rect width="760" height="470" fill="#ffffff"/>
+<text x="74" y="30" font-size="19" font-weight="700" fill="#1f2937">Guest block storage throughput (Viperblock)</text>
+<text x="74" y="49" font-size="12.5" fill="#6b7280">fio, 4 jobs, iodepth 32, direct I/O, per-guest sequential runs — Spinifex v1.20.0</text>
+<line x1="74" y1="386.0" x2="734" y2="386.0" stroke="#e5e7eb" stroke-width="1"/>
+<text x="64" y="390.0" font-size="12" text-anchor="end" fill="#6b7280">0</text>
+<line x1="74" y1="305.0" x2="734" y2="305.0" stroke="#e5e7eb" stroke-width="1"/>
+<text x="64" y="309.0" font-size="12" text-anchor="end" fill="#6b7280">100</text>
+<line x1="74" y1="224.0" x2="734" y2="224.0" stroke="#e5e7eb" stroke-width="1"/>
+<text x="64" y="228.0" font-size="12" text-anchor="end" fill="#6b7280">200</text>
+<line x1="74" y1="143.0" x2="734" y2="143.0" stroke="#e5e7eb" stroke-width="1"/>
+<text x="64" y="147.0" font-size="12" text-anchor="end" fill="#6b7280">300</text>
+<line x1="74" y1="62.0" x2="734" y2="62.0" stroke="#e5e7eb" stroke-width="1"/>
+<text x="64" y="66.0" font-size="12" text-anchor="end" fill="#6b7280">400</text>
+<text x="22" y="224.0" font-size="12.5" fill="#6b7280" transform="rotate(-90 22 224.0)" text-anchor="middle">MiB/s</text>
+<rect x="111.4" y="81.4" width="45.4" height="304.6" rx="2.5" fill="#2563eb"/>
+<text x="134.1" y="75.4" font-size="11" text-anchor="middle" fill="#1f2937">376</text>
+<rect x="159.8" y="198.1" width="45.4" height="187.9" rx="2.5" fill="#0d9488"/>
+<text x="182.5" y="192.1" font-size="11" text-anchor="middle" fill="#1f2937">232</text>
+<rect x="208.2" y="299.3" width="45.4" height="86.7" rx="2.5" fill="#f59e0b"/>
+<text x="230.9" y="293.3" font-size="11" text-anchor="middle" fill="#1f2937">107</text>
+<text x="184.0" y="408.0" font-size="13" text-anchor="middle" font-weight="600" fill="#1f2937">GPU</text>
+<rect x="331.4" y="85.5" width="45.4" height="300.5" rx="2.5" fill="#2563eb"/>
+<text x="354.1" y="79.5" font-size="11" text-anchor="middle" fill="#1f2937">371</text>
+<rect x="379.8" y="202.9" width="45.4" height="183.1" rx="2.5" fill="#0d9488"/>
+<text x="402.5" y="196.9" font-size="11" text-anchor="middle" fill="#1f2937">226</text>
+<rect x="428.2" y="321.2" width="45.4" height="64.8" rx="2.5" fill="#f59e0b"/>
+<text x="450.9" y="315.2" font-size="11" text-anchor="middle" fill="#1f2937">80</text>
+<text x="404.0" y="408.0" font-size="13" text-anchor="middle" font-weight="600" fill="#1f2937">CPU1</text>
+<rect x="551.4" y="84.7" width="45.4" height="301.3" rx="2.5" fill="#2563eb"/>
+<text x="574.1" y="78.7" font-size="11" text-anchor="middle" fill="#1f2937">372</text>
+<rect x="599.8" y="201.3" width="45.4" height="184.7" rx="2.5" fill="#0d9488"/>
+<text x="622.5" y="195.3" font-size="11" text-anchor="middle" fill="#1f2937">228</text>
+<rect x="648.2" y="321.2" width="45.4" height="64.8" rx="2.5" fill="#f59e0b"/>
+<text x="670.9" y="315.2" font-size="11" text-anchor="middle" fill="#1f2937">80</text>
+<text x="624.0" y="408.0" font-size="13" text-anchor="middle" font-weight="600" fill="#1f2937">CPU2</text>
+<line x1="74" y1="386" x2="734" y2="386" stroke="#1f2937" stroke-width="1.5"/>
+<rect x="74" y="444" width="13" height="13" rx="2.5" fill="#2563eb"/>
+<text x="93" y="455" font-size="12.5" fill="#1f2937">128K random read</text>
+<rect x="216.8" y="444" width="13" height="13" rx="2.5" fill="#0d9488"/>
+<text x="235.8" y="455" font-size="12.5" fill="#1f2937">128K mixed read</text>
+<rect x="352.3" y="444" width="13" height="13" rx="2.5" fill="#f59e0b"/>
+<text x="371.3" y="455" font-size="12.5" fill="#1f2937">16K random read</text>
+</svg>

.github/assets/images/cisco-ucs-platform-benchmark/network-goodput-vs-streams.svg

@@ -0,0 +1,35 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="470" viewBox="0 0 760 470" font-family="-apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif">
+<rect width="760" height="470" fill="#ffffff"/>
+<text x="74" y="30" font-size="19" font-weight="700" fill="#1f2937">Network throughput: overlay vs physical fabric</text>
+<text x="74" y="49" font-size="12.5" fill="#6b7280">iperf3 TCP receiver goodput, median across node pairs — Spinifex v1.20.0</text>
+<line x1="74" y1="386.0" x2="734" y2="386.0" stroke="#e5e7eb" stroke-width="1"/>
+<text x="64" y="390.0" font-size="12" text-anchor="end" fill="#6b7280">20</text>
+<line x1="74" y1="62.0" x2="734" y2="62.0" stroke="#e5e7eb" stroke-width="1"/>
+<text x="64" y="66.0" font-size="12" text-anchor="end" fill="#6b7280">25</text>
+<text x="22" y="224.0" font-size="12.5" fill="#6b7280" transform="rotate(-90 22 224.0)" text-anchor="middle">Gbit/s</text>
+<text x="140.0" y="408.0" font-size="13" text-anchor="middle" font-weight="600" fill="#1f2937">1</text>
+<text x="272.0" y="408.0" font-size="13" text-anchor="middle" font-weight="600" fill="#1f2937">2</text>
+<text x="404.0" y="408.0" font-size="13" text-anchor="middle" font-weight="600" fill="#1f2937">4</text>
+<text x="536.0" y="408.0" font-size="13" text-anchor="middle" font-weight="600" fill="#1f2937">8</text>
+<text x="668.0" y="408.0" font-size="13" text-anchor="middle" font-weight="600" fill="#1f2937">16</text>
+<path d="M140.0,164.4 L272.0,160.5 L404.0,160.5 L536.0,160.5 L668.0,160.5" fill="none" stroke="#2563eb" stroke-width="3"/>
+<circle cx="140.0" cy="164.4" r="4.5" fill="#fff" stroke="#2563eb" stroke-width="2.5"/>
+<circle cx="272.0" cy="160.5" r="4.5" fill="#fff" stroke="#2563eb" stroke-width="2.5"/>
+<circle cx="404.0" cy="160.5" r="4.5" fill="#fff" stroke="#2563eb" stroke-width="2.5"/>
+<circle cx="536.0" cy="160.5" r="4.5" fill="#fff" stroke="#2563eb" stroke-width="2.5"/>
+<circle cx="668.0" cy="160.5" r="4.5" fill="#fff" stroke="#2563eb" stroke-width="2.5"/>
+<text x="664.0" y="149.5" font-size="11.5" text-anchor="end" font-weight="600" fill="#2563eb">23.48</text>
+<path d="M140.0,255.1 L272.0,222.1 L404.0,222.1 L536.0,222.1 L668.0,228.5" fill="none" stroke="#0d9488" stroke-width="3"/>
+<circle cx="140.0" cy="255.1" r="4.5" fill="#fff" stroke="#0d9488" stroke-width="2.5"/>
+<circle cx="272.0" cy="222.1" r="4.5" fill="#fff" stroke="#0d9488" stroke-width="2.5"/>
+<circle cx="404.0" cy="222.1" r="4.5" fill="#fff" stroke="#0d9488" stroke-width="2.5"/>
+<circle cx="536.0" cy="222.1" r="4.5" fill="#fff" stroke="#0d9488" stroke-width="2.5"/>
+<circle cx="668.0" cy="228.5" r="4.5" fill="#fff" stroke="#0d9488" stroke-width="2.5"/>
+<text x="664.0" y="217.5" font-size="11.5" text-anchor="end" font-weight="600" fill="#0d9488">22.43</text>
+<line x1="74" y1="386" x2="734" y2="386" stroke="#1f2937" stroke-width="1.5"/>
+<text x="404.0" y="430.0" font-size="12.5" text-anchor="middle" fill="#6b7280">parallel TCP streams</text>
+<rect x="74" y="444" width="13" height="13" rx="2.5" fill="#2563eb"/>
+<text x="93" y="455" font-size="12.5" fill="#1f2937">Host physical fabric (25GbE)</text>
+<rect x="304.4" y="444" width="13" height="13" rx="2.5" fill="#0d9488"/>
+<text x="323.4" y="455" font-size="12.5" fill="#1f2937">Guest overlay (OVN)</text>
+</svg>

.github/assets/images/cisco-ucs-platform-benchmark/predastore-s3-read-by-client.svg

@@ -0,0 +1,39 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="470" viewBox="0 0 760 470" font-family="-apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif">
+<rect width="760" height="470" fill="#ffffff"/>
+<text x="74" y="30" font-size="19" font-weight="700" fill="#1f2937">Predastore S3 read throughput by client</text>
+<text x="74" y="49" font-size="12.5" fill="#6b7280">1 GiB objects, same presigned-curl client on every path — Spinifex v1.20.0</text>
+<line x1="74" y1="386.0" x2="734" y2="386.0" stroke="#e5e7eb" stroke-width="1"/>
+<text x="64" y="390.0" font-size="12" text-anchor="end" fill="#6b7280">0</text>
+<line x1="74" y1="278.0" x2="734" y2="278.0" stroke="#e5e7eb" stroke-width="1"/>
+<text x="64" y="282.0" font-size="12" text-anchor="end" fill="#6b7280">200</text>
+<line x1="74" y1="170.0" x2="734" y2="170.0" stroke="#e5e7eb" stroke-width="1"/>
+<text x="64" y="174.0" font-size="12" text-anchor="end" fill="#6b7280">400</text>
+<line x1="74" y1="62.0" x2="734" y2="62.0" stroke="#e5e7eb" stroke-width="1"/>
+<text x="64" y="66.0" font-size="12" text-anchor="end" fill="#6b7280">600</text>
+<text x="22" y="224.0" font-size="12.5" fill="#6b7280" transform="rotate(-90 22 224.0)" text-anchor="middle">MiB/s</text>
+<rect x="102.0" y="202.4" width="51.5" height="183.6" rx="2.5" fill="#2563eb"/>
+<text x="127.8" y="196.4" font-size="11" text-anchor="middle" fill="#1f2937">340</text>
+<rect x="156.5" y="136.5" width="51.5" height="249.5" rx="2.5" fill="#f59e0b"/>
+<text x="182.2" y="130.5" font-size="11" text-anchor="middle" fill="#1f2937">462</text>
+<text x="156.5" y="408.0" font-size="13" text-anchor="middle" font-weight="600" fill="#1f2937">Host</text>
+<rect x="267.1" y="170.5" width="51.5" height="215.5" rx="2.5" fill="#2563eb"/>
+<text x="292.8" y="164.5" font-size="11" text-anchor="middle" fill="#1f2937">399</text>
+<rect x="321.5" y="174.9" width="51.5" height="211.1" rx="2.5" fill="#f59e0b"/>
+<text x="347.2" y="168.9" font-size="11" text-anchor="middle" fill="#1f2937">391</text>
+<text x="321.5" y="408.0" font-size="13" text-anchor="middle" font-weight="600" fill="#1f2937">GPU guest</text>
+<rect x="432.1" y="102.5" width="51.5" height="283.5" rx="2.5" fill="#2563eb"/>
+<text x="457.8" y="96.5" font-size="11" text-anchor="middle" fill="#1f2937">525</text>
+<rect x="486.5" y="197.0" width="51.5" height="189.0" rx="2.5" fill="#f59e0b"/>
+<text x="512.2" y="191.0" font-size="11" text-anchor="middle" fill="#1f2937">350</text>
+<text x="486.5" y="408.0" font-size="13" text-anchor="middle" font-weight="600" fill="#1f2937">CPU1 guest</text>
+<rect x="597.0" y="106.8" width="51.5" height="279.2" rx="2.5" fill="#2563eb"/>
+<text x="622.8" y="100.8" font-size="11" text-anchor="middle" fill="#1f2937">517</text>
+<rect x="651.5" y="196.5" width="51.5" height="189.5" rx="2.5" fill="#f59e0b"/>
+<text x="677.2" y="190.5" font-size="11" text-anchor="middle" fill="#1f2937">351</text>
+<text x="651.5" y="408.0" font-size="13" text-anchor="middle" font-weight="600" fill="#1f2937">CPU2 guest</text>
+<line x1="74" y1="386" x2="734" y2="386" stroke="#1f2937" stroke-width="1.5"/>
+<rect x="74" y="444" width="13" height="13" rx="2.5" fill="#2563eb"/>
+<text x="93" y="455" font-size="12.5" fill="#1f2937">Single-stream GET</text>
+<rect x="224.1" y="444" width="13" height="13" rx="2.5" fill="#f59e0b"/>
+<text x="243.1" y="455" font-size="12.5" fill="#1f2937">Chunked/concurrent GET</text>
+</svg>

.github/dependabot.yml

@@ -23,11 +23,6 @@ updates:
       timezone: Australia/Sydney
     cooldown:
       default-days: 3
-    ignore:
-      - dependency-name: "*"
-        update-types:
-          - "version-update:semver-minor"
-          - "version-update:semver-patch"
     groups:
       github-actions:
         patterns:
@@ -35,7 +30,7 @@ updates:
 
   - package-ecosystem: npm
     target-branch: dev
-    directory: /spinifex/services/spinifexui/frontend
+    directory: /spinifex/runtime/roles/spinifexui/frontend
     schedule:
       interval: weekly
       day: sunday
@@ -50,3 +45,28 @@ updates:
       npm-dependencies:
         patterns:
           - "*"
+
+  # Base images are pinned by digest, so this is what moves them. The golang
+  # version is deliberate and changes with go.mod; only its digest moves here.
+  - package-ecosystem: docker
+    target-branch: dev
+    directories:
+      - /build
+      - /scripts
+      - /docs/terraform-workbooks/demo-app
+    schedule:
+      interval: weekly
+      day: sunday
+      timezone: Australia/Sydney
+    cooldown:
+      default-days: 3
+    ignore:
+      - dependency-name: golang
+        update-types:
+          - "version-update:semver-major"
+          - "version-update:semver-minor"
+          - "version-update:semver-patch"
+    groups:
+      docker-images:
+        patterns:
+          - "*"

.github/e2e-cells.json

@@ -0,0 +1,194 @@
+[
+  {
+    "cell": 1,
+    "install": "binary",
+    "topo": "single",
+    "net": "dhcp",
+    "host": "debian-13",
+    "arch": "x86_64",
+    "runner": "ci-single",
+    "extra": "",
+    "suite": ""
+  },
+  {
+    "cell": 2,
+    "install": "binary",
+    "topo": "single",
+    "net": "static",
+    "host": "ubuntu-26.04",
+    "arch": "x86_64",
+    "runner": "ci-single",
+    "extra": "",
+    "suite": ""
+  },
+  {
+    "cell": 3,
+    "install": "binary",
+    "topo": "single",
+    "net": "dhcp",
+    "host": "ubuntu-26.04",
+    "arch": "x86_64",
+    "runner": "ci-single",
+    "extra": "",
+    "suite": ""
+  },
+  {
+    "cell": 8,
+    "install": "binary",
+    "topo": "real-multi",
+    "net": "dhcp",
+    "host": "debian-13",
+    "arch": "x86_64",
+    "runner": "ci-multi",
+    "extra": "",
+    "suite": ""
+  },
+  {
+    "cell": 9,
+    "install": "binary",
+    "topo": "real-multi",
+    "net": "static",
+    "host": "ubuntu-26.04",
+    "arch": "x86_64",
+    "runner": "ci-multi",
+    "extra": "",
+    "suite": ""
+  },
+  {
+    "cell": 10,
+    "install": "binary",
+    "topo": "real-multi",
+    "net": "dhcp",
+    "host": "ubuntu-26.04",
+    "arch": "x86_64",
+    "runner": "ci-multi",
+    "extra": "",
+    "suite": ""
+  },
+  {
+    "cell": 17,
+    "install": "binary",
+    "topo": "single",
+    "net": "static",
+    "host": "debian-13",
+    "arch": "x86_64",
+    "runner": "ci-pseudo",
+    "extra": "tofu-examples",
+    "suite": ""
+  },
+  {
+    "cell": 18,
+    "install": "binary",
+    "topo": "single",
+    "net": "static",
+    "host": "debian-13",
+    "arch": "x86_64",
+    "runner": "ci-single",
+    "extra": "reboot-single",
+    "suite": ""
+  },
+  {
+    "cell": 19,
+    "install": "binary",
+    "topo": "single",
+    "net": "nat",
+    "host": "debian-13",
+    "arch": "x86_64",
+    "runner": "ci-single",
+    "extra": "nat-single",
+    "suite": ""
+  },
+  {
+    "cell": 25,
+    "install": "binary",
+    "topo": "single",
+    "net": "static",
+    "host": "debian-13",
+    "arch": "x86_64",
+    "runner": "ci-single-nvme",
+    "extra": "eks",
+    "suite": "eks"
+  },
+  {
+    "cell": 26,
+    "install": "binary",
+    "topo": "single",
+    "net": "static",
+    "host": "debian-13",
+    "arch": "x86_64",
+    "runner": "ci-single",
+    "extra": "ecs",
+    "suite": "ecs"
+  },
+  {
+    "cell": 27,
+    "install": "binary",
+    "topo": "single",
+    "net": "static",
+    "host": "debian-13",
+    "arch": "x86_64",
+    "runner": "ci-single",
+    "extra": "rds",
+    "suite": "rds",
+    "timeout_minutes": 120
+  },
+  {
+    "cell": 29,
+    "install": "binary",
+    "topo": "real-multi",
+    "net": "static",
+    "host": "debian-13",
+    "arch": "x86_64",
+    "runner": "ci-multi",
+    "extra": "",
+    "suite": "storagefault",
+    "timeout_minutes": 100
+  },
+  {
+    "cell": 30,
+    "install": "binary",
+    "topo": "real-multi",
+    "net": "nat",
+    "host": "debian-13",
+    "arch": "x86_64",
+    "runner": "ci-multi",
+    "extra": "nat-multi",
+    "suite": ""
+  },
+  {
+    "cell": 31,
+    "install": "binary",
+    "topo": "real-multi",
+    "net": "static",
+    "host": "debian-13",
+    "arch": "x86_64",
+    "runner": "ci-multi",
+    "extra": "",
+    "suite": "instancerecovery",
+    "timeout_minutes": 105
+  },
+  {
+    "cell": 32,
+    "install": "binary",
+    "topo": "real-multi",
+    "net": "static",
+    "host": "debian-13",
+    "arch": "x86_64",
+    "runner": "ci-multi",
+    "extra": "",
+    "suite": "lbrecovery",
+    "timeout_minutes": 90
+  },
+  {
+    "cell": 33,
+    "install": "binary",
+    "topo": "real-multi",
+    "net": "static",
+    "host": "debian-13",
+    "arch": "x86_64",
+    "runner": "ci-multi",
+    "extra": "",
+    "suite": "kvquorum",
+    "timeout_minutes": 55
+  }
+]

.github/pull_request_template.md

@@ -5,3 +5,17 @@
 ## Changes
 
 <!-- The notable changes, as bullets. -->
+
+## Account-scoped lifecycle impact
+
+<!-- Complete this section only when the PR changes account-scoped resource lifecycle, account termination, resource cleanup, or a lifecycle boundary. Otherwise write: N/A. -->
+
+- Lifecycle owner and resource family:
+- Owner-local ordering, recovery, retained-state, or force impact:
+- Cross-domain dependency or ownership impact:
+- Evidence added or rechecked:
+- ADR-0008 lifecycle register / ADR-0001 migration-record / bead updates:
+
+## Community Contribution License
+
+- [ ] All community contributions in this pull request are licensed to Mulga under the terms of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). By creating this pull request I represent that I have the right to license these contributions to Mulga under the Apache License 2.0.

.github/resolve-release-sibling-refs.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Resolve the tag of each sibling repo (viperblock, predastore, northstar,
+# bluebottle) a release build checks out. A release ships what go.mod requires,
+# so each sibling is built at the version go.mod names, never a branch tip. A
+# pseudo-version has no tag to check out, so it fails the release rather than
+# silently building something else.
+#
+# Takes the path to spinifex's go.mod and writes viperblock=<tag>,
+# predastore=<tag>, northstar=<tag> and bluebottle=<tag> to $GITHUB_OUTPUT for
+# the checkout steps to consume.
+set -euo pipefail
+
+gomod="${1:?usage: $0 <path to spinifex go.mod>}"
+: "${GITHUB_OUTPUT:?GITHUB_OUTPUT must be set}"
+
+for repo in viperblock predastore northstar bluebottle; do
+  module="github.com/mulgadc/${repo}"
+  version=$(awk -v m="$module" '$1 == m { print $2; exit }' "$gomod")
+  if [[ -z "$version" ]]; then
+    echo "::error::${gomod} does not require ${module}"
+    exit 1
+  fi
+  if [[ ! "$version" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ || "$version" =~ [0-9]{14}-[0-9a-f]{12}$ ]]; then
+    echo "::error::${module} is required at ${version}, which is not a release tag; tag ${repo} and bump go.mod before releasing"
+    exit 1
+  fi
+  echo "${repo}: building against ${version}"
+  echo "${repo}=${version}" >>"$GITHUB_OUTPUT"
+done

.github/scripts/ci-fmt.sh

@@ -61,3 +61,37 @@ quiet_run() {
     return "$rc"
   fi
 }
+
+# Connection-layer failures from the libvirt tofu provider. The socket drops
+# when a hypervisor is carrying several environments at once, which is the
+# steady state here. A resource that failed to build says something else.
+CI_LIBVIRT_TRANSIENT='Unable to Connect to Libvirt|error connecting to libvirt|procedure interrupted|Cannot recv data|Cannot write data|End of file while reading data'
+
+# retry_run LABEL LOG_FILE -- CMD ARGS …
+# quiet_run with a bounded retry, taken only when that attempt's own output
+# names a libvirt connection failure. Every other failure is reported on the
+# first attempt, so a real bug never becomes a slow flake.
+retry_run() {
+  local label="$1" log="$2"; shift 2
+  local _attempts="${CI_RETRY_ATTEMPTS:-3}" _delay="${CI_RETRY_DELAY:-30}" _i _rc=1 _mark
+  for ((_i = 1; _i <= _attempts; _i++)); do
+    _mark=$(wc -c < "$log" 2>/dev/null || echo 0)
+    # rc must be read inside the else: an `if` whose condition fails and has no
+    # else exits 0, so reading $? after `fi` reports success for a failed run.
+    if "$@" >> "$log" 2>&1; then
+      if [[ $_i -gt 1 ]]; then ok "$label (libvirt recovered on attempt $_i)"; else ok "$label"; fi
+      return 0
+    else
+      _rc=$?
+    fi
+    tail -c "+$((_mark + 1))" "$log" | grep -Eq "$CI_LIBVIRT_TRANSIENT" || break
+    [[ $_i -eq $_attempts ]] && break
+    warn "$label: libvirt connection dropped (attempt $_i/$_attempts), retrying in ${_delay}s"
+    sleep "$_delay"
+  done
+  bad "$label (rc=$_rc) — last 80 lines of $(basename "$log"):"
+  group_open "tail $(basename "$log")"
+  tail -n 80 "$log"
+  group_close
+  return "$_rc"
+}

.github/scripts/e2e-run-summary.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""Render one run-level table for the e2e nightly into the job summary.
+
+Reading a nightly meant opening nineteen jobs, and the Actions UI does not
+distinguish a cell that failed from one that was cancelled out from under it —
+a distinction every investigation of this suite has needed.
+
+Inputs (env):
+    GITHUB_TOKEN         Token with actions:read.
+    GITHUB_REPOSITORY    owner/repo.
+    GITHUB_RUN_ID        Run to summarise.
+    JUNIT_ROOT           Directory holding downloaded junit-cell-* artifacts.
+    GITHUB_STEP_SUMMARY  Appended to.
+
+Test counts come from the junit artifacts; result, duration and runner come
+from the jobs API, so a cell that died before writing junit still gets a row.
+"""
+
+from __future__ import annotations
+
+import glob
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+import xml.etree.ElementTree as ET
+from datetime import datetime
+
+API = "https://api.github.com"
+
+# A cell whose job produced no verdict is not a pass and not a failure. Keeping
+# them apart is the point of the table.
+VERDICT_ICON = {
+    "success": "✅",
+    "failure": "❌",
+    "cancelled": "🚫",
+    "skipped": "⏭️",
+    "timed_out": "⏱️",
+}
+
+
+def fetch_jobs(repo: str, run_id: str, token: str) -> list[dict]:
+    jobs: list[dict] = []
+    page = 1
+    while True:
+        url = f"{API}/repos/{repo}/actions/runs/{run_id}/jobs?per_page=100&page={page}"
+        req = urllib.request.Request(
+            url,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                payload = json.load(resp)
+        except (urllib.error.URLError, TimeoutError) as exc:
+            print(f"::warning::jobs API page {page} failed: {exc}", file=sys.stderr)
+            break
+        batch = payload.get("jobs", [])
+        jobs.extend(batch)
+        if len(batch) < 100:
+            break
+        page += 1
+    return jobs
+
+
+def duration_s(job: dict) -> int | None:
+    started, completed = job.get("started_at"), job.get("completed_at")
+    if not started or not completed:
+        return None
+    fmt = "%Y-%m-%dT%H:%M:%SZ"
+    try:
+        return int((datetime.strptime(completed, fmt) - datetime.strptime(started, fmt)).total_seconds())
+    except ValueError:
+        return None
+
+
+def human(seconds: int | None) -> str:
+    if seconds is None:
+        return "—"
+    if seconds < 0:
+        return "0s"
+    return f"{seconds // 60}m{seconds % 60:02d}s" if seconds >= 60 else f"{seconds}s"
+
+
+def junit_counts(root: str) -> dict[str, dict]:
+    """Map cell number to its aggregate junit counts and failing test names."""
+    per_cell: dict[str, dict] = {}
+    for path in glob.glob(os.path.join(root, "**", "junit-*.xml"), recursive=True):
+        cell = cell_from_artifact_path(path)
+        if cell is None:
+            continue
+        acc = per_cell.setdefault(cell, {"tests": 0, "failures": 0, "skipped": 0, "failing": []})
+        try:
+            root_el = ET.parse(path).getroot()
+        except ET.ParseError as exc:
+            print(f"::warning::unparseable junit {path}: {exc}", file=sys.stderr)
+            continue
+        suites = root_el.iter("testsuite") if root_el.tag != "testsuite" else [root_el]
+        for suite in suites:
+            acc["tests"] += int(suite.get("tests") or 0)
+            acc["failures"] += int(suite.get("failures") or 0) + int(suite.get("errors") or 0)
+            acc["skipped"] += int(suite.get("skipped") or 0)
+        for case in root_el.iter("testcase"):
+            if case.find("failure") is not None or case.find("error") is not None:
+                name = case.get("name") or "?"
+                if name not in acc["failing"]:
+                    acc["failing"].append(name)
+    return per_cell
+
+
+def cell_from_artifact_path(path: str) -> str | None:
+    """Recover the cell number from a junit-cell-<n>-<run_id> artifact directory."""
+    for part in path.split(os.sep):
+        if part.startswith("junit-cell-"):
+            rest = part[len("junit-cell-"):]
+            cell = rest.split("-", 1)[0]
+            return cell if cell.isdigit() else None
+    return None
+
+
+def cell_number(job_name: str) -> str | None:
+    """cell-19 (single/static/debian-13) -> 19."""
+    if not job_name.startswith("cell-"):
+        return None
+    cell = job_name[len("cell-"):].split(" ", 1)[0]
+    return cell if cell.isdigit() else None
+
+
+def main() -> int:
+    repo = os.environ.get("GITHUB_REPOSITORY", "")
+    run_id = os.environ.get("GITHUB_RUN_ID", "")
+    token = os.environ.get("GITHUB_TOKEN", "")
+    summary_path = os.environ.get("GITHUB_STEP_SUMMARY", "")
+    junit_root = os.environ.get("JUNIT_ROOT", "")
+
+    if not (repo and run_id and token and summary_path):
+        print("::warning::e2e-run-summary: missing required environment", file=sys.stderr)
+        return 0
+
+    jobs = fetch_jobs(repo, run_id, token)
+    counts = junit_counts(junit_root) if junit_root and os.path.isdir(junit_root) else {}
+
+    rows = []
+    for job in jobs:
+        cell = cell_number(job.get("name", ""))
+        if cell is None:
+            continue
+        rows.append((int(cell), job))
+    rows.sort(key=lambda r: r[0])
+
+    lines = [f"## e2e nightly — run summary ({len(rows)} cells)", ""]
+    if not rows:
+        lines.append("No cell jobs found for this run.")
+        write(summary_path, lines)
+        return 0
+
+    lines += [
+        "| Cell | Topology | Result | Duration | Runner | Tests | Failed | Skipped |",
+        "| --- | --- | --- | --- | --- | --- | --- | --- |",
+    ]
+
+    tally: dict[str, int] = {}
+    total_tests = total_failed = total_seconds = 0
+    failing_detail: list[tuple[int, list[str]]] = []
+
+    for cell, job in rows:
+        name = job.get("name", "")
+        # A cell dispatched to a reusable workflow reports as
+        # "cell-20 (baremetal/pxe/real-hw) / Bare-Metal Single-Node E2E".
+        topo = name.split("(", 1)[1].split(")", 1)[0] if "(" in name else "—"
+        verdict = job.get("conclusion") or job.get("status") or "unknown"
+        tally[verdict] = tally.get(verdict, 0) + 1
+        secs = duration_s(job)
+        total_seconds += secs or 0
+        c = counts.get(str(cell), {})
+        total_tests += c.get("tests", 0)
+        total_failed += c.get("failures", 0)
+        if c.get("failing"):
+            failing_detail.append((cell, c["failing"]))
+        lines.append(
+            f"| {cell} | {topo} | {VERDICT_ICON.get(verdict, '❔')} {verdict} | {human(secs)} "
+            f"| {job.get('runner_name') or '—'} | {c.get('tests', '—')} "
+            f"| {c.get('failures', '—')} | {c.get('skipped', '—')} |"
+        )
+
+    verdicts = ", ".join(f"{n} {v}" for v, n in sorted(tally.items(), key=lambda kv: -kv[1]))
+    lines += [
+        "",
+        f"**Cells:** {verdicts}",
+        f"**Tests:** {total_tests} run, {total_failed} failed",
+        f"**Cell wall clock:** {human(total_seconds)} across all cells",
+    ]
+
+    slowest = sorted(rows, key=lambda r: duration_s(r[1]) or 0, reverse=True)[:3]
+    if slowest:
+        lines.append(
+            "**Slowest:** " + ", ".join(f"cell {c} ({human(duration_s(j))})" for c, j in slowest)
+        )
+
+    if failing_detail:
+        lines += ["", "<details><summary>Failing tests</summary>", ""]
+        for cell, names in failing_detail:
+            lines.append(f"- **cell {cell}** — " + ", ".join(f"`{n}`" for n in names))
+        lines += ["", "</details>"]
+
+    write(summary_path, lines)
+    return 0
+
+
+def write(path: str, lines: list[str]) -> None:
+    with open(path, "a", encoding="utf-8") as fh:
+        fh.write("\n".join(lines) + "\n")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/scripts/ensure-libguestfs.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Prepare a runner to build a guest image with build-system-image.sh.
+#
+# Installs libguestfs + qemu-utils if they are missing and makes a host kernel
+# readable, so the libguestfs appliance can boot. Nothing here touches a host
+# block device: virt-customize works inside an isolated userspace appliance, so
+# this is safe on a shared runner.
+#
+# Callers must still export LIBGUESTFS_BACKEND=direct themselves — it has to be
+# set in the environment the build runs in, which is not this subshell.
+set -euo pipefail
+
+# Three nightly service cells share one ci-single runner and start together, so
+# concurrent apt-get runs are the normal case rather than the exception. Two of
+# them lost the lock outright before this guard existed. Skipping the install
+# when the tools are already present avoids most of the contention; the lock
+# timeout covers the rest, including apt runs started by anything else on the
+# box.
+if command -v virt-customize >/dev/null && command -v qemu-img >/dev/null; then
+    echo "libguestfs-tools and qemu-utils already present"
+else
+    APT_OPTS=(-o DPkg::Lock::Timeout=600)
+    sudo apt-get "${APT_OPTS[@]}" update -qq
+    sudo apt-get "${APT_OPTS[@]}" install -y --no-install-recommends \
+        libguestfs-tools qemu-utils
+fi
+
+# Debian/Ubuntu ship /boot/vmlinuz-* mode 0600 and the appliance needs to read a
+# host kernel. Tolerated on failure: a runner whose kernel is already readable
+# has no vmlinuz to chmod under some images.
+sudo chmod 0644 /boot/vmlinuz-* || true

.github/scripts/suite-sets.sh

@@ -28,23 +28,122 @@
 # that runs identically on either, and because a quota left switched on would
 # cap every suite sharing the environment — so it must be proved to restore
 # itself wherever it runs, not only on one node.
-E2E_SUITES_SINGLE="single iam cert eks ecs storagegrowth partialblock rds quota"
+# storagefault runs last in both lists and belongs to both topologies, for
+# different reasons. On one node it is RS(1,0), so freezing the only predastore
+# is a total outage and the guest-survival assertion is unambiguous. On three it
+# is RS(2,1) with degraded writes on, so two must be frozen to break the shard
+# floor — and only there is a cross-node restart possible at all, which is the
+# case that takes a volume over from a node holding writes the backend never
+# received. It is last because it SIGSTOPs a cluster-wide
+# service: anything sharing the environment would see the same outage and report
+# a failure that says nothing about itself.
+E2E_SUITES_SINGLE="single iam cert eks ecs storagegrowth partialblock rds quota storagefault"
 
 # Suites runnable against a multi-node environment.
-E2E_SUITES_MULTI="multinode lb cert quota"
+#
+# instancerecovery is multi-only and needs three: recovery is inert below that,
+# because there is no survivor to move a guest to that is not the node that
+# failed. Like storagefault it takes a node away and freezes a cluster-wide
+# service, so it runs last and owns its environment.
+#
+# lbrecovery is multi-only and needs three for two reasons rather than one: a
+# survivor to move the load balancer to, and a node for its backends that is not
+# the load balancer's, so taking that node away does not take the backends with
+# it. It runs beside instancerecovery at the end because it also takes a node
+# away and owns its environment while it does.
+#
+# kvquorum is multi-only and needs three, for the same reason as those two: a
+# surviving majority. It is what proves the control plane's own state is
+# replicated rather than sitting on one node, so it runs before the pair that
+# take a node away — a cluster whose buckets are already wrong should report
+# that, not report a recovery failing.
+E2E_SUITES_MULTI="multinode lb cert quota kvquorum lbrecovery instancerecovery storagefault"
 
 # grep -xE alternation form, for narrowing a requested set to the eligible one.
 E2E_SUITES_SINGLE_RE="$(printf '%s' "${E2E_SUITES_SINGLE}" | tr ' ' '|')"
 E2E_SUITES_MULTI_RE="$(printf '%s' "${E2E_SUITES_MULTI}" | tr ' ' '|')"
 
-# e2e-nightly runs a narrower set than the two sets above, deliberately: its
-# ~19 cells each have a 35-minute budget and exist to prove that every
-# install / network / host-OS permutation boots and serves. Suite breadth is
-# the PR gate's job, and it already runs on every push. These are subsets, and
-# e2e_suites_assert_subset below enforces that.
-E2E_SUITES_NIGHTLY_SINGLE="single cert"
+# What every e2e-nightly permutation cell must prove, deliberately narrower
+# than the two sets above: those cells have a 35-minute budget and exist to show
+# that every install / network / host-OS combination boots and serves. The
+# service suites are not deferred to the PR gate — eks, ecs and rds each run
+# nightly in their own dedicated cell, because each needs a guest AMI built
+# first and a service failure should not mask whether a host OS boots. These
+# are subsets, and e2e_suites_assert_subset below enforces that.
+#
+# storagefault has a dedicated cell for two reasons. It SIGSTOPs a cluster-wide
+# service, so in a permutation cell every suite sharing that environment would
+# report the outage as its own failure. And a full pass is ~63 minutes, nearly
+# all of it deliberate waiting, which is too long to add to the PR gate — where
+# it has never run, since the gate's default suite list does not name it.
+#
+# Its cell is three-node: the RS(2,1) shard floor and the cross-node takeover
+# after a failed seal do not exist on one node, and they are the assertions
+# worth a nightly.
+E2E_SUITES_NIGHTLY_SINGLE="single cert iam"
+#
+# The multi-node nightly subset carries kvquorum's read-only half through
+# `multinode`, which sweeps every KV bucket rather than the three the daemon
+# owns. The node-loss half is too slow for a 35-minute cell and has its own.
 E2E_SUITES_NIGHTLY_MULTI="multinode cert lb"
 
+# How long a suite gets, for the same reason the lists above live here: the
+# timeout was written out separately in each workflow and drifted, so rds ran
+# 50m on the PR gate and 30m nightly and panicked there. A suite needing more
+# than the default declares it once, here.
+#   e2e_suite_timeout <suite>
+e2e_suite_timeout() {
+  case "$1" in
+    # rds serialises its DB VMs behind a 3 GiB semaphore, so its wall clock is
+    # what the queue costs, not what the tests do: single tests logged 11m, 22m
+    # and 26m waiting for budget. 17 tests at that concurrency is over an hour
+    # before anything goes wrong, and the first pass to run deep into the suite
+    # still had three left at 60m. The loaded graceful-reboot case adds an
+    # instance that holds its slot through a pgbench load as well as a create.
+    rds) echo "105m" ;;
+    # diskperf runs two 16 GiB fio profiles per repetition, each on a volume it
+    # creates first. One pass is ~20 minutes on the bare-metal cell and a
+    # baseline capture at SPINIFEX_DISKPERF_REPS=3 is three times that.
+    diskperf) echo "180m" ;;
+    # storagefault is mostly deliberate waiting: one test alone holds predastore
+    # SIGSTOPped for seven minutes to prove a guest survives it. A full pass on
+    # dev-prod is ~63 minutes, so the 30m default truncated it mid-suite.
+    storagefault) echo "90m" ;;
+    # instancerecovery is almost entirely waiting, and none of it is avoidable:
+    # a dead owner has to be seen stale twice, a guest has to boot, and the
+    # storage case waits for a pause measured at 4m47s and then holds four
+    # minutes to prove nothing moved. Three tests, each taking a node away and
+    # bringing it back, and the partition case adds a lease validity, a lease
+    # TTL and a boot on top of everything the other two wait for.
+    instancerecovery) echo "90m" ;;
+    # lbrecovery pays for a load balancer twice: once to stand one up with two
+    # backends placed around it, and once for the recovery itself — a stale
+    # owner, a lease, a boot, HAProxy's own start, and its health checks against
+    # the backends before it forwards anything. Then the node comes back and has
+    # to be shown not to answer for an address it no longer holds.
+    lbrecovery) echo "75m" ;;
+    # kvquorum audits every bucket in seconds and then spends the rest of its
+    # budget on a node stopping and starting: seven units down, a raft election,
+    # and the whole service stack back up with every stream caught up.
+    kvquorum) echo "40m" ;;
+    *) echo "30m" ;;
+  esac
+}
+
+# One matrix leg per suite, carrying the job budget that suite needs. The outer
+# timeout must always be later than the `go test` one inside it: go test reports
+# where it stopped, a cancelled job reports only "The operation was canceled".
+#   e2e_suite_matrix <suite-list> <floor-minutes> [allowance-minutes]
+e2e_suite_matrix() {
+  local list="$1" floor="$2" allowance="${3:-15}" suite budget
+  for suite in ${list}; do
+    budget="$(e2e_suite_timeout "${suite}")"
+    budget=$((${budget%m} + allowance))
+    if [ "${budget}" -lt "${floor}" ]; then budget="${floor}"; fi
+    printf '%s\t%s\n' "${suite}" "${budget}"
+  done | jq -cRs 'split("\n")|map(select(length>0)|split("\t")|{suite:.[0],timeout:(.[1]|tonumber)})'
+}
+
 # Fail loudly when a narrowed list names a suite its topology cannot run. This
 # is the guard that stops the lists drifting again: a suite added to a nightly
 # subset without also being declared eligible above stops the job here rather

.github/workflows/actions.lock

@@ -0,0 +1,137 @@
+# This file is machine-generated by `gh actions-lock`.
+# Do not edit by hand; run `gh actions-lock` to update.
+# Docs: https://gh.io/actions-lockfile
+version: 'v0.0.3'
+workflows:
+    '.github/workflows/apt-packages.yml':
+        - 'actions/checkout@v7.0.1'
+    '.github/workflows/dev-release.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/setup-go@v7.0.0'
+        - 'docker/setup-buildx-action@v4.4.1'
+    '.github/workflows/e2e-baremetal.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/create-github-app-token@v3.3.0'
+        - 'actions/upload-artifact@v7.0.2'
+    '.github/workflows/e2e-cloudvendor-nightly.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/create-github-app-token@v3.3.0'
+        - 'actions/upload-artifact@v7.0.2'
+        - 'hashicorp/setup-terraform@v4.0.1'
+    '.github/workflows/e2e-ddil.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/create-github-app-token@v3.3.0'
+        - 'actions/upload-artifact@v7.0.2'
+    '.github/workflows/e2e-nightly.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/create-github-app-token@v3.3.0'
+        - 'actions/download-artifact@v8.0.2'
+        - 'actions/upload-artifact@v7.0.2'
+    '.github/workflows/e2e-suites.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/create-github-app-token@v3.3.0'
+        - 'actions/setup-go@v7.0.0'
+        - 'actions/upload-artifact@v7.0.2'
+    '.github/workflows/e2e.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/create-github-app-token@v3.3.0'
+        - 'actions/download-artifact@v8.0.2'
+        - 'actions/setup-go@v7.0.0'
+        - 'actions/upload-artifact@v7.0.2'
+    '.github/workflows/gpu-e2e.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/setup-go@v7.0.0'
+        - 'actions/upload-artifact@v7.0.2'
+    '.github/workflows/image-scripts.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/setup-go@v7.0.0'
+    '.github/workflows/perf-3node.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/create-github-app-token@v3.3.0'
+        - 'actions/setup-go@v7.0.0'
+        - 'actions/upload-artifact@v7.0.2'
+    '.github/workflows/publish-system-ami.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/setup-go@v7.0.0'
+    '.github/workflows/release.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/create-github-app-token@v3.3.0'
+        - 'actions/download-artifact@v8.0.2'
+        - 'actions/setup-go@v7.0.0'
+        - 'actions/upload-artifact@v7.0.2'
+        - 'docker/setup-buildx-action@v4.4.1'
+        - 'softprops/action-gh-release@v3.0.3'
+    '.github/workflows/segscan-oracle.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/create-github-app-token@v3.3.0'
+        - 'actions/setup-go@v7.0.0'
+    '.github/workflows/spinifex.yml':
+        - 'actions/cache@v6.1.0'
+        - 'actions/checkout@v7.0.1'
+        - 'actions/setup-go@v7.0.0'
+        - 'golangci/golangci-lint-action@v9.3.0'
+    '.github/workflows/ui.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/setup-node@v7.1.0'
+        - 'pnpm/action-setup@v6.1.0'
+dependencies:
+    'actions/cache@v6.1.0':
+        ref: 'v6.1.0'
+        commit: 'sha1-55cc8345863c7cc4c66a329aec7e433d2d1c52a9'
+        owner_id: 44036562
+        repo_id: 215566462
+    'actions/checkout@v7.0.1':
+        ref: 'v7.0.1'
+        commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1'
+        owner_id: 44036562
+        repo_id: 197814629
+    'actions/create-github-app-token@v3.3.0':
+        ref: 'v3.3.0'
+        commit: 'sha1-64ab729a6294000f5aa4a4bc0b73d1f32bc45510'
+        owner_id: 44036562
+        repo_id: 642580244
+    'actions/download-artifact@v8.0.2':
+        ref: 'v8.0.2'
+        commit: 'sha1-9000827ccba6bdab643e8b6fd33ac0654aef8333'
+        owner_id: 44036562
+        repo_id: 192626254
+    'actions/setup-go@v7.0.0':
+        ref: 'v7.0.0'
+        commit: 'sha1-b7ad1dad31e06c5925ef5d2fc7ad053ef454303e'
+        owner_id: 44036562
+        repo_id: 192624594
+    'actions/setup-node@v7.1.0':
+        ref: 'v7.1.0'
+        commit: 'sha1-949feb2413d6458794dcd2491c4babbbce0c15c1'
+        owner_id: 44036562
+        repo_id: 189476904
+    'actions/upload-artifact@v7.0.2':
+        ref: 'v7.0.2'
+        commit: 'sha1-cf430e030ddbb5b0abf93d22962f4752f3646cd9'
+        owner_id: 44036562
+        repo_id: 192625955
+    'docker/setup-buildx-action@v4.4.1':
+        ref: 'v4.4.1'
+        commit: 'sha1-f87e5991a6d7451dcb8d9637bfbc97413f497069'
+        owner_id: 5429470
+        repo_id: 288485773
+    'golangci/golangci-lint-action@v9.3.0':
+        ref: 'v9.3.0'
+        commit: 'sha1-ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a'
+        owner_id: 35628013
+        repo_id: 232539879
+    'hashicorp/setup-terraform@v4.0.1':
+        ref: 'v4.0.1'
+        commit: 'sha1-dfe3c3f87815947d99a8997f908cb6525fc44e9e'
+        owner_id: 761456
+        repo_id: 258271226
+    'pnpm/action-setup@v6.1.0':
+        ref: 'v6.1.0'
+        commit: 'sha1-ea17c68df8912ef543352723c149a84f56e3d413'
+        owner_id: 21320719
+        repo_id: 262289747
+    'softprops/action-gh-release@v3.0.3':
+        ref: 'v3.0.3'
+        commit: 'sha1-efb35369e0ad2afab669f228072c1b0d510eae64'
+        owner_id: 2242
+        repo_id: 204253808

.github/workflows/apt-packages.yml

@@ -33,8 +33,6 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # The suites the nightly E2E matrix actually installs on. Ubuntu 22.04 is
-        # accepted by detect_os but has never been exercised and does not resolve.
         image:
           - ubuntu:24.04
           - ubuntu:26.04
@@ -42,7 +40,7 @@ jobs:
 
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
 
       - name: Resolve runtime package list
         run: ./scripts/lint-apt-packages.sh ${{ matrix.image }}

.github/workflows/dev-release.yml

@@ -0,0 +1,185 @@
+name: Dev Prerelease
+
+# Publishes the dev channel that install.mulgadc.com already serves. setup.sh has
+# understood INSTALL_SPINIFEX_CHANNEL=dev since it was written and the install
+# Worker resolves that channel to the newest GitHub prerelease, but nothing has
+# ever produced one -- so /download/dev/amd64 returned 404. This is the producer.
+#
+# A separate workflow rather than conditionals in release.yml, because a dev build
+# is a different artifact and not a release with flags off: amd64 only, no ISO, no
+# AMI refresh, no bare-metal gate, and nothing that touches a self-hosted runner.
+on:
+  push:
+    branches: [dev]
+    # Nothing here changes the binary, and a prerelease per docs commit would
+    # churn the channel our contacts are installing from.
+    paths-ignore:
+      - "docs/**"
+      - "**/*.md"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+# Supersede rather than queue: on a run of merges to dev only the newest commit is
+# worth publishing, and the older build would land after it and become the channel.
+concurrency:
+  group: dev-release
+  cancel-in-progress: true
+
+jobs:
+  prerelease:
+    runs-on: ubuntu-26.04
+    steps:
+      # Full history and tags, because the tag name is git describe and a shallow
+      # clone has no tag to describe against.
+      - name: Checkout Spinifex
+        uses: actions/checkout@v7.0.1
+        with:
+          path: spinifex
+          fetch-depth: 0
+
+      # dev, not each repository's default branch, which is what release.yml takes.
+      # A dev build of spinifex against main of the others is a pairing nobody runs.
+      - name: Checkout Predastore
+        uses: actions/checkout@v7.0.1
+        with:
+          repository: mulgadc/predastore
+          ref: dev
+          path: predastore
+
+      - name: Checkout Viperblock
+        uses: actions/checkout@v7.0.1
+        with:
+          repository: mulgadc/viperblock
+          ref: dev
+          path: viperblock
+
+      - name: Checkout Northstar
+        uses: actions/checkout@v7.0.1
+        with:
+          repository: mulgadc/northstar
+          ref: dev
+          path: northstar
+
+      - name: Checkout Bluebottle
+        uses: actions/checkout@v7.0.1
+        with:
+          repository: mulgadc/bluebottle
+          ref: dev
+          path: bluebottle
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4.4.1
+
+      - name: Set up Go
+        uses: actions/setup-go@v7.0.0
+        with:
+          go-version-file: spinifex/go.mod
+          cache: false
+
+      # The tag carries the describe string so the commit is recoverable from the
+      # version alone, and the -dev suffix is what release.yml's own convention
+      # already treats as a prerelease. VERSION must equal the tag: the install
+      # Worker derives the asset name from the tag it resolves.
+      - name: Resolve the version
+        id: version
+        working-directory: spinifex
+        run: |
+          set -euo pipefail
+          # Describing against a dev tag would nest it, growing the name every release.
+          TAG="$(git describe --tags --always --exclude '*-dev')-dev"
+          case "$TAG" in
+              v*) ;;
+              *) echo "::error::git describe gave '$TAG', which is not a v-prefixed version"; exit 1 ;;
+          esac
+          if gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+              echo "::notice::$TAG already published; nothing to do"
+              echo "exists=true" >> "$GITHUB_OUTPUT"
+          fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "Publishing $TAG"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - name: Build microVM artifacts (lb-agent + kernel + initramfs)
+        if: steps.version.outputs.exists != 'true'
+        run: cd spinifex && make build-microvm-image
+
+      - name: Build amd64 Tarball
+        if: steps.version.outputs.exists != 'true'
+        env:
+          VERSION: ${{ steps.version.outputs.tag }}
+        run: cd spinifex && make distro-amd64 VERSION="$VERSION"
+
+      # --prerelease on create, never a later promote step. release.yml sets it in
+      # a job that runs after its verification gates, which leaves a window where
+      # the release is not flagged; GitHub's releases/latest excludes prereleases
+      # only, so in that window a dev build is what every customer curl installs.
+      - name: Publish the prerelease
+        if: steps.version.outputs.exists != 'true'
+        working-directory: spinifex
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          set -euo pipefail
+          # A file, not an inline string: the notes are Markdown, and leading
+          # whitespace from indenting a shell literal turns them into code blocks.
+          cat > "$RUNNER_TEMP/notes.md" <<EOF
+          Automated dev-channel build of \`$GITHUB_SHA\`.
+
+          **Not a release.** amd64 only, no ISO and no system images, and it has not been through the release verification gates. Install it with:
+
+          \`\`\`
+          curl -sfL https://install.mulgadc.com | sudo bash -s -- --channel dev
+          \`\`\`
+          EOF
+          sed -i 's/^          //' "$RUNNER_TEMP/notes.md"
+          gh release create "$TAG" \
+              --repo "$GITHUB_REPOSITORY" \
+              --target "$GITHUB_SHA" \
+              --prerelease \
+              --title "$TAG" \
+              --notes-file "$RUNNER_TEMP/notes.md" \
+              "dist/spinifex-$TAG-linux-amd64.tar.gz" \
+              "dist/spinifex-$TAG-linux-amd64.tar.gz.sha256" \
+              "scripts/setup.sh"
+
+      # The assertion that matters. A prerelease must never become the latest
+      # release, because latest is what an unqualified curl | bash installs -- so
+      # this checks the published state rather than trusting the flag we passed.
+      - name: Assert the stable channel is untouched
+        if: steps.version.outputs.exists != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          set -euo pipefail
+          latest="$(gh api "repos/$GITHUB_REPOSITORY/releases/latest" --jq .tag_name)"
+          if [ "$latest" = "$TAG" ]; then
+              echo "::error::$TAG became the latest release: every customer curl | bash would install it"
+              gh release edit "$TAG" --repo "$GITHUB_REPOSITORY" --prerelease
+              exit 1
+          fi
+          echo "latest is still $latest"
+          dev="$(gh api "repos/$GITHUB_REPOSITORY/releases?per_page=20" --jq 'map(select(.prerelease))[0].tag_name')"
+          [ "$dev" = "$TAG" ] || { echo "::error::the dev channel resolves to $dev, not $TAG"; exit 1; }
+
+      # Kept rather than unbounded: the Worker reads the first page of releases to
+      # resolve the channel, so enough prereleases would eventually push the real
+      # ones off it. Five leaves a few recent builds to roll back to.
+      - name: Prune old dev prereleases
+        if: steps.version.outputs.exists != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          gh api "repos/$GITHUB_REPOSITORY/releases?per_page=100" \
+              --jq 'map(select(.prerelease and (.tag_name | endswith("-dev")))) | .[5:] | .[].tag_name' \
+              > stale.txt
+          while read -r tag; do
+              [ -n "$tag" ] || continue
+              echo "deleting $tag"
+              gh release delete "$tag" --repo "$GITHUB_REPOSITORY" --yes --cleanup-tag
+          done < stale.txt

.github/workflows/e2e-baremetal.yml

@@ -1,7 +1,26 @@
 name: E2E Bare-Metal
 
 on:
+  # Mirrors the suite selection of workflow_call so a baseline capture can be
+  # driven by hand. A dispatch run sees only the inputs declared here, so
+  # omitting these would silently fall back to the correctness set.
   workflow_dispatch:
+    inputs:
+      suites:
+        description: "Space-separated e2e suites to run on the node. Default is the correctness set; a performance run names its own so its numbers come off an otherwise idle cell"
+        required: false
+        type: string
+        default: "single cert lb"
+      suite-env:
+        description: "Extra environment for the suite invocation, e.g. SPINIFEX_DISKPERF_REPS=3"
+        required: false
+        type: string
+        default: ""
+      cell:
+        description: "Nightly cell number this run reports as. Names the artifact bundle and the ES dimension, so two callers of this workflow stay distinguishable in the sink"
+        required: false
+        type: string
+        default: "20"
   workflow_call:
     inputs:
       ref:
@@ -14,6 +33,21 @@ on:
         required: false
         type: string
         default: ""
+      suites:
+        description: "Space-separated e2e suites to run on the node. Default is the correctness set; a performance caller names its own so its numbers come off an otherwise idle cell"
+        required: false
+        type: string
+        default: "single cert lb"
+      suite-env:
+        description: "Extra environment for the suite invocation, e.g. SPINIFEX_DISKPERF_REPS=3"
+        required: false
+        type: string
+        default: ""
+      cell:
+        description: "Nightly cell number this run reports as. Names the artifact bundle and the ES dimension, so two callers of this workflow stay distinguishable in the sink"
+        required: false
+        type: string
+        default: "20"
 
 permissions:
   contents: read
@@ -21,25 +55,21 @@ permissions:
 
 env:
   GIT_BRANCH: ${{ github.ref_name }}
-  # Same central ES/APM sink as the other four e2e workflows. Bare-metal had
-  # no default here before — this cell's telemetry never reached the sink at
-  # all (not just missing ci.cell), see bm-bootstrap.sh's telemetry.env step.
   SPINIFEX_OTLP_ENDPOINT: ${{ vars.SPINIFEX_OTLP_ENDPOINT || 'http://192.168.1.13:8200' }}
 
 jobs:
   e2e_baremetal:
     name: Bare-Metal Single-Node E2E
-    runs-on: [ self-hosted, ci-baremetal ]
-    timeout-minutes: 120
+    runs-on: [self-hosted, ci-baremetal]
+    timeout-minutes: 240
     concurrency:
       group: e2e-baremetal-cluster
       cancel-in-progress: false
     env:
       BM_ISO_CACHE: /var/cache/spinifex-iso-builder
-      ARTIFACT_DIR: /tmp/spinifex-e2e-nightly-cell-20-${{ github.run_id }}
-      # Caller-supplied (workflow_call input); empty for a manual
-      # workflow_dispatch run, which bm-bootstrap.sh treats as "no attrs".
-      SPINIFEX_OTEL_ATTRS: ${{ inputs.otel-attrs }}
+      BM_CELL: ${{ inputs.cell || '20' }}
+      ARTIFACT_DIR: /tmp/spinifex-e2e-nightly-cell-${{ inputs.cell || '20' }}-${{ github.run_id }}
+      SPINIFEX_OTEL_ATTRS: ${{ inputs.otel-attrs || format('ci.run_id={0},ci.workflow={1},ci.cell={2},ci.matrix=baremetal/pxe/real-hw', github.run_id, github.workflow, inputs.cell || '20') }}
     steps:
       - name: Clean Workspace
         run: |
@@ -47,18 +77,18 @@ jobs:
           if [ ! -c /dev/null ]; then sudo rm -f /dev/null; sudo mknod -m 666 /dev/null c 1 3; fi
           sudo rm -rf --one-file-system "$GITHUB_WORKSPACE"/*
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           ref: ${{ inputs.ref || github.ref }}
 
-      - uses: actions/create-github-app-token@v3
+      - uses: actions/create-github-app-token@v3.3.0
         id: app-token
         with:
           client-id: ${{ secrets.APP_ID }}
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
           repositories: mulga
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/mulga
           token: ${{ steps.app-token.outputs.token }}
@@ -74,6 +104,10 @@ jobs:
           ssh-keygen -y -f "${RUNNER_TEMP}/bm-ci" > "${RUNNER_TEMP}/bm-ci.pub"
 
       - name: Build Artifacts
+        env:
+          # The node runs pre-built binaries, so a suite absent here cannot be
+          # selected later. Same list as the run step for that reason.
+          BM_SUITES: ${{ inputs.suites || 'single cert lb' }}
         run: |
           mulga/scripts/baremetal/bm-build-artifacts.sh \
             "$GITHUB_WORKSPACE" \
@@ -89,7 +123,7 @@ jobs:
             INSTALLER_BIN="${RUNNER_TEMP}/bm-bins/spinifex-installer" \
             SPINIFEX_SRC="${GITHUB_WORKSPACE}" \
             VIPERBLOCK_SRC="${RUNNER_TEMP}/bm-bins/viperblock" \
-            VERSION="$(cd "$GITHUB_WORKSPACE" && git describe --tags --always 2>/dev/null || echo dev)"
+            VERSION="$(cd "$GITHUB_WORKSPACE" && git describe --tags --always --exclude '*-dev' 2>/dev/null || echo dev)"
 
       - name: Write ePDU credentials
         run: |
@@ -117,7 +151,23 @@ jobs:
           fi
 
       - name: Install go-junit-report on runner
-        run: go install github.com/jstemmer/go-junit-report/v2@latest
+        # Version from go.mod's tool directive, checked against go.sum.
+        run: GOWORK=off go install github.com/jstemmer/go-junit-report/v2
+
+      # The eks suite's CreateCluster boots a control-plane VM from the eks-node
+      # AMI. Built here because libguestfs needs source and network, which the
+      # runner has and the PXE-booted node does not; bm-bootstrap.sh imports it.
+      - name: Build eks-node AMI (libguestfs, runner)
+        if: contains(inputs.suites, 'eks')
+        run: |
+          set -euo pipefail
+          # direct backend = no libvirt. Set here rather than in the script:
+          # it has to be in the environment the build itself runs in.
+          export LIBGUESTFS_BACKEND=direct
+          # spinifex is the workspace root here, unlike the nightly where it is
+          # checked out into a subdirectory.
+          "${GITHUB_WORKSPACE}/.github/scripts/ensure-libguestfs.sh"
+          make build-eks-node-image
 
       - name: Run Bare-Metal E2E
         env:
@@ -126,9 +176,25 @@ jobs:
           BM_EPDU_ENV: ${{ runner.temp }}/epdu.env
           BM_UBUNTU_IMAGE: ${{ env.BM_ISO_CACHE }}/ubuntu-26.04-cloudimg-amd64.img
           SPX_EXTERNAL_POOL: ${{ env.SPINIFEX_CI_POOL }}
+          BM_SUITES: ${{ inputs.suites || 'single cert lb' }}
+          BM_SUITE_ENV: ${{ inputs.suite-env }}
+          # Empty unless the eks build above ran, and bm-bootstrap.sh skips the
+          # import when unset, so the other suites are unaffected.
+          BM_EKS_IMAGE: ${{ contains(inputs.suites, 'eks') && '/tmp/eks-node-image-build/eks-node-alpine.raw' || '' }}
+          BM_EKS_MANIFEST: ${{ contains(inputs.suites, 'eks') && format('{0}/scripts/images/eks-node/manifest.conf', github.workspace) || '' }}
         run: |
           mkdir -p "${ARTIFACT_DIR}"
           set -o pipefail
+          . "${GITHUB_WORKSPACE}/.github/scripts/suite-sets.sh"
+          BM_TEST_TIMEOUT=""
+          for suite in ${BM_SUITES}; do
+            tmo="$(e2e_suite_timeout "${suite}")"
+            if [ -z "${BM_TEST_TIMEOUT}" ] || [ "${tmo%m}" -gt "${BM_TEST_TIMEOUT%m}" ]; then
+              BM_TEST_TIMEOUT="${tmo}"
+            fi
+          done
+          export BM_TEST_TIMEOUT
+          echo "suites=${BM_SUITES} test-timeout=${BM_TEST_TIMEOUT}"
           sudo -E mulga/scripts/baremetal/run-baremetal-e2e.sh \
             --vmlinuz   "${BM_ISO_CACHE}/vmlinuz" \
             --initrd    "${BM_ISO_CACHE}/initrd.img" \
@@ -139,7 +205,15 @@ jobs:
       - name: Generate JUnit report
         if: always()
         run: |
-          LOG="${ARTIFACT_DIR}/test-baremetal.log"
+          # suite-output.log, not test-baremetal.log. The harness streams the
+          # full suite output to the first and a grep-filtered summary to its
+          # stdout, and that filter anchors --- PASS at column 0, so every
+          # indented subtest result is dropped. Parsed from the filtered log,
+          # go-junit-report saw a === RUN with no result and emitted
+          # <error message="No test result found"> — 17 of 39 testcases on a
+          # green cell-28, 93 of 120 on cell-20.
+          LOG="${ARTIFACT_DIR}/suite-output.log"
+          [ -s "$LOG" ] || LOG="${ARTIFACT_DIR}/test-baremetal.log"
           [ -f "$LOG" ] || exit 0
           go-junit-report -in "$LOG" -out "${ARTIFACT_DIR}/junit-baremetal.xml" || true
 
@@ -148,23 +222,23 @@ jobs:
       - name: Ship test results to Elasticsearch
         if: always()
         continue-on-error: true
-        uses: ./.github/actions/junit-to-es
+        uses: $/.github/actions/junit-to-es
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
-          cell: "20"
+          cell: ${{ env.BM_CELL }}
 
       - name: Analyze e2e failures
         if: always()
-        uses: ./.github/actions/e2e-analyze
+        uses: $/.github/actions/e2e-analyze
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           log-dir: ${{ env.ARTIFACT_DIR }}
-          title: "E2E failure analysis (cell 20)"
+          title: "E2E failure analysis (cell ${{ env.BM_CELL }})"
 
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@v7.0.2
         if: always()
         with:
-          name: e2e-artifacts-cell-20-${{ github.run_id }}
+          name: e2e-artifacts-cell-${{ env.BM_CELL }}-${{ github.run_id }}
           path: ${{ env.ARTIFACT_DIR }}
           if-no-files-found: warn
           retention-days: 14

.github/workflows/e2e-cloudvendor-nightly.yml

@@ -0,0 +1,287 @@
+name: E2E Cloud Vendor Nightly
+
+# Dispatched by the same Cloudflare Worker that drives e2e-nightly.yml, once per
+# ref, rather than by a `schedule:` here. GitHub registers a schedule only from
+# the default branch, so a cron in this file could never run `dev` and a feature
+# branch as separate nightlies, and it would always execute the default branch's
+# copy of this file -- leaving a fix to the workflow itself untestable until it
+# had already shipped. A dispatch takes both the file and the source from its ref.
+on:
+  workflow_dispatch:
+    inputs:
+      topologies:
+        description: "Space-separated topologies (blank = vm-single vm-multi bm vm-single-principal). One name runs one topology."
+        required: false
+      workbooks:
+        description: "Space-separated workbooks (blank = the driver's default list)"
+        required: false
+      source:
+        description: "tree (build this ref) or release (the published installer)"
+        required: false
+        default: tree
+      channel:
+        description: "With source=release: latest, or dev for the newest prerelease"
+        required: false
+        default: latest
+      keep_on_fail:
+        description: "Leave a failed topology up to inspect. It keeps billing."
+        required: false
+        type: boolean
+        default: false
+      auth:
+        description: "How nodes reach the OCI API: instance_principal (needs the tenancy dynamic group) or api_key (needs the credential hook). The vm-single-principal topology always uses instance_principal."
+        required: false
+        default: instance_principal
+        type: choice
+        options: [instance_principal, api_key]
+      no_external_pool:
+        description: "Form without the OCI allocator. Skips every workbook needing a public address. Not applied to vm-single-principal."
+        required: false
+        type: boolean
+        default: false
+      runner:
+        description: "Runner label (blank = the OCI_E2E_RUNNER variable, else ubuntu-26.04)"
+        required: false
+
+permissions:
+  contents: read
+
+# Every topology is built in one OCI compartment under one set of resource names,
+# so two runs at once would each see the other's instances and the sweep in
+# e2e-oci.sh could destroy a cluster the other run was still testing. Queue the
+# second rather than cancelling it: a dispatch is usually a verification run.
+concurrency:
+  group: e2e-oci
+  cancel-in-progress: false
+
+jobs:
+  oci:
+    # Hosted by default: this job only drives Terraform and SSH, and the work
+    # happens on OCI, so nothing here needs a hypervisor. Overridable because the
+    # argument for a per-provider self-hosted runner is control, not capacity --
+    # a dedicated label keeps a two-hour cloud wait off the hypervisor labels and
+    # lifts the six-hour cap a hosted job carries.
+    runs-on: ${{ inputs.runner || vars.OCI_E2E_RUNNER || 'ubuntu-26.04' }}
+    # Three topologies including a bare-metal build, each with its own install,
+    # formation and workbook pass. The sweep still runs if this fires.
+    timeout-minutes: 300
+    steps:
+      # Set here rather than in a job-level env block: the runner context is not
+      # available at job level, only from a step onwards, and a workflow that
+      # references it there is rejected as invalid before any job starts.
+      #
+      # Outside github.workspace on purpose. The checkout wipes untracked files, so
+      # on a persistent runner it would delete the Terraform state of a killed run
+      # before the next sweep could read it, leaving instances nothing can find.
+      - name: Put the Terraform state outside the checkout
+        run: echo "OCI_STATE_ROOT=$RUNNER_WORKSPACE/oci-state" >> "$GITHUB_ENV"
+
+      - uses: actions/checkout@v7.0.1
+        with:
+          path: spinifex
+
+      - uses: actions/create-github-app-token@v3.3.0
+        id: app-token
+        with:
+          client-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+          # mulga alone. It is the only private repository of the six, and the
+          # five that build-install-artifacts.sh clones are public, so the builder
+          # needs no credential and this token is not widened to reach them.
+          repositories: mulga
+
+      # build-install-artifacts.sh lives in mulga. The workbooks and their driver
+      # are in spinifex, so only the one directory is needed here.
+      - uses: actions/checkout@v7.0.1
+        with:
+          repository: mulgadc/mulga
+          path: mulga
+          token: ${{ steps.app-token.outputs.token }}
+          sparse-checkout: scripts/tofu-cluster
+
+      - uses: hashicorp/setup-terraform@v4.0.1
+        with:
+          terraform_wrapper: false
+
+      # Written to the runner's own filesystem and nowhere else. The OCI API
+      # credential is not here at all: it reaches Terraform as OCI_PRIVATE_KEY in
+      # the environment, so no key file is ever created.
+      - name: Install the throwaway SSH key
+        env:
+          OCI_E2E_SSH_PRIVATE_KEY: ${{ secrets.OCI_E2E_SSH_PRIVATE_KEY }}
+          OCI_E2E_SSH_PUBLIC_KEY: ${{ secrets.OCI_E2E_SSH_PUBLIC_KEY }}
+        run: |
+          set -euo pipefail
+          mkdir -p ~/.ssh
+          printf '%s\n' "$OCI_E2E_SSH_PRIVATE_KEY" > ~/.ssh/oci-spx
+          printf '%s\n' "$OCI_E2E_SSH_PUBLIC_KEY" > ~/.ssh/oci-spx.pub
+          chmod 600 ~/.ssh/oci-spx
+          ssh-keygen -y -f ~/.ssh/oci-spx > /dev/null
+
+      - name: Run the OCI topologies
+        working-directory: spinifex/scripts/terraform/oci-spx
+        env:
+          OCI_TENANCY_OCID: ${{ secrets.OCI_TENANCY_OCID }}
+          OCI_USER_OCID: ${{ secrets.OCI_USER_OCID }}
+          OCI_FINGERPRINT: ${{ secrets.OCI_FINGERPRINT }}
+          OCI_PRIVATE_KEY: ${{ secrets.OCI_PRIVATE_KEY }}
+          OCI_REGION: ${{ vars.OCI_REGION || 'ap-sydney-1' }}
+          TF_VAR_compartment_ocid: ${{ secrets.OCI_COMPARTMENT_OCID }}
+          MULGA_ROOT: ${{ github.workspace }}/mulga
+          SPX_REF: ${{ github.ref_name }}
+          OCI_TOPOLOGIES: ${{ inputs.topologies }}
+          OCI_SOURCE: ${{ inputs.source }}
+          OCI_CHANNEL: ${{ inputs.channel }}
+          # Independent of the pool, deliberately. These were one switch, which made
+          # the combination we actually need -- an API key with the allocator running
+          # -- impossible to ask for, so public-IP allocation went untested.
+          OCI_INSTANCE_PRINCIPAL: ${{ inputs.auth == 'api_key' && '0' || '1' }}
+          # Skipping the pool records the allocator and every public-address workbook
+          # as SKIPPED, so a green run with this set is not a claim about guest
+          # networking. It exists for a formation-only check, not as a way past a
+          # missing credential.
+          OCI_NO_EXTERNAL_POOL: ${{ inputs.no_external_pool && '1' || '0' }}
+          # Only an API-key run needs one: an instance principal is the node's own
+          # certificate, so there is nothing to hand over. Unset is not an error, and
+          # the allocator gate then fails rather than passing a node that cannot
+          # authenticate.
+          OCI_CREDENTIAL_HOOK: ${{ inputs.auth == 'api_key' && vars.OCI_CREDENTIAL_HOOK || '' }}
+          # vm-single-principal builds in its own tenancy. The dynamic group it needs
+          # is a tenancy-root resource, and the shared test tenancy grants us only
+          # compartment rights, so that topology can never pass there however correct
+          # the code is. Unset skips it rather than spending a provision to fail.
+          OCI_PRINCIPAL_TENANCY_OCID: ${{ secrets.OCI_PRINCIPAL_TENANCY_OCID }}
+          OCI_PRINCIPAL_USER_OCID: ${{ secrets.OCI_PRINCIPAL_USER_OCID }}
+          OCI_PRINCIPAL_FINGERPRINT: ${{ secrets.OCI_PRINCIPAL_FINGERPRINT }}
+          OCI_PRINCIPAL_PRIVATE_KEY: ${{ secrets.OCI_PRINCIPAL_PRIVATE_KEY }}
+          OCI_PRINCIPAL_COMPARTMENT_OCID: ${{ secrets.OCI_PRINCIPAL_COMPARTMENT_OCID }}
+          OCI_PRINCIPAL_REGION: ${{ vars.OCI_PRINCIPAL_REGION }}
+          # Service limits are per tenancy, so the shape the other topologies use
+          # can have zero quota in this one. Ours has no E6 cores at all, and the
+          # apply then fails before anything about the principal is exercised.
+          OCI_PRINCIPAL_SHAPE: ${{ vars.OCI_PRINCIPAL_SHAPE }}
+          OCI_ARTIFACT_DIR: ${{ runner.temp }}/e2e-oci
+          OCI_KEEP_ON_FAIL: ${{ inputs.keep_on_fail && '1' || '0' }}
+          # Through the environment, never interpolated into the script below: a
+          # dispatch input is attacker-controlled text as far as the shell is
+          # concerned, and a quote in it would otherwise end the string.
+          WORKBOOKS_INPUT: ${{ inputs.workbooks }}
+        run: |
+          set -uo pipefail
+          # WORKBOOKS is exported only when the dispatch named some: the harness
+          # distinguishes unset (the driver's default list) from empty (run none).
+          if [ -n "$WORKBOOKS_INPUT" ]; then export WORKBOOKS="$WORKBOOKS_INPUT"; fi
+          ./e2e-oci.sh 2>&1 | tee "$RUNNER_TEMP/e2e-oci.log"
+          exit "${PIPESTATUS[0]}"
+
+      # Before the sweep, which destroys the state the tables are read from, and
+      # always(): a run whose verdict is a failure is exactly the one somebody
+      # wants a table for. The successful path writes the same tables itself, so
+      # this step is for the run that did not get there.
+      #
+      # The markdown lives in the script rather than here. A heredoc in a YAML
+      # string is the one place in this repository nothing can lint or run.
+      - name: Publish the result tables
+        if: always()
+        working-directory: spinifex/scripts/terraform/oci-spx
+        env:
+          OCI_REGION: ${{ vars.OCI_REGION || 'ap-sydney-1' }}
+          OCI_ARTIFACT_DIR: ${{ runner.temp }}/e2e-oci
+          OCI_TOPOLOGIES: ${{ inputs.topologies }}
+          OCI_SOURCE: ${{ inputs.source }}
+          OCI_CHANNEL: ${{ inputs.channel }}
+          SPX_REF: ${{ github.ref_name }}
+          # The same two the run step passes. The header states what was and was not
+          # tested, so a summary rendered without them would claim more than the run.
+          OCI_INSTANCE_PRINCIPAL: ${{ inputs.auth == 'api_key' && '0' || '1' }}
+          OCI_NO_EXTERNAL_POOL: ${{ inputs.no_external_pool && '1' || '0' }}
+        run: ./e2e-oci.sh --summary-only
+
+      # The sweep below deletes the per-topology state directories, so anything
+      # still only in one of them at that point is unrecoverable -- and a failing
+      # workbook writes its assertion output to exactly there. Copying into the
+      # artifact directory first is what makes a failure diagnosable by whoever
+      # reads the run page, rather than only on the runner that produced it.
+      - name: Collect the per-topology logs
+        if: always()
+        run: |
+          set -uo pipefail
+          dest="$RUNNER_TEMP/e2e-oci"
+          mkdir -p "$dest"
+          # The topologies this run drove, taken from the per-topology log the
+          # harness writes rather than from the dispatch input: a run that names
+          # none gets the harness's own default, and reading that back here would
+          # mean a second copy of the list to disagree with the first. A state
+          # directory left by an earlier run is then not collected, so the artifact
+          # cannot show a topology this run never attempted.
+          topologies=""
+          for log in "$dest"/*.log; do
+              [ -f "$log" ] || continue
+              name="${log##*/}"; name="${name%.log}"
+              [ -d "$OCI_STATE_ROOT/.validate-$name" ] && topologies="$topologies $name"
+          done
+          echo "collecting:${topologies:- nothing}"
+          for topology in $topologies; do
+              for file in "$OCI_STATE_ROOT/.validate-$topology"/*.log \
+                          "$OCI_STATE_ROOT/.validate-$topology"/*.txt \
+                          "$OCI_STATE_ROOT/.validate-$topology"/*.tsv; do
+                  [ -f "$file" ] || continue
+                  # The hook handles a private key and the one thing known about an
+                  # operator's executable is that it is not ours to publish.
+                  case "${file##*/}" in credential-hook.log) continue ;; esac
+                  cp -- "$file" "$dest/$topology-${file##*/}"
+              done
+          done
+          ls -l "$dest"
+
+      # always(), and before the artifact upload: an OCI bare-metal host left
+      # running by a cancelled or timed-out job is the most expensive way this
+      # workflow can fail. The sweep works from the Terraform state files, so it
+      # can only destroy what this run created.
+      - name: Sweep anything left behind
+        if: always() && !inputs.keep_on_fail
+        working-directory: spinifex/scripts/terraform/oci-spx
+        env:
+          OCI_TENANCY_OCID: ${{ secrets.OCI_TENANCY_OCID }}
+          OCI_USER_OCID: ${{ secrets.OCI_USER_OCID }}
+          OCI_FINGERPRINT: ${{ secrets.OCI_FINGERPRINT }}
+          OCI_PRIVATE_KEY: ${{ secrets.OCI_PRIVATE_KEY }}
+          OCI_REGION: ${{ vars.OCI_REGION || 'ap-sydney-1' }}
+          TF_VAR_compartment_ocid: ${{ secrets.OCI_COMPARTMENT_OCID }}
+          # The sweep destroys by state file, so it needs whichever tenancy each
+          # topology built in. Without these a leftover principal deployment is
+          # swept against a tenancy that never held it and reported clean.
+          OCI_PRINCIPAL_TENANCY_OCID: ${{ secrets.OCI_PRINCIPAL_TENANCY_OCID }}
+          OCI_PRINCIPAL_USER_OCID: ${{ secrets.OCI_PRINCIPAL_USER_OCID }}
+          OCI_PRINCIPAL_FINGERPRINT: ${{ secrets.OCI_PRINCIPAL_FINGERPRINT }}
+          OCI_PRINCIPAL_PRIVATE_KEY: ${{ secrets.OCI_PRINCIPAL_PRIVATE_KEY }}
+          OCI_PRINCIPAL_COMPARTMENT_OCID: ${{ secrets.OCI_PRINCIPAL_COMPARTMENT_OCID }}
+          OCI_PRINCIPAL_REGION: ${{ vars.OCI_PRINCIPAL_REGION }}
+          OCI_ARTIFACT_DIR: ${{ runner.temp }}/e2e-oci-sweep
+        run: ./e2e-oci.sh --sweep-only
+
+      # Explicit, not left to the runner's own cleanup: a hosted runner is
+      # discarded after the job, but a self-hosted one keeps $HOME, so the key
+      # would outlive the run that needed it and sit there between nightlies.
+      - name: Remove the throwaway SSH key
+        if: always()
+        run: rm -f ~/.ssh/oci-spx ~/.ssh/oci-spx.pub
+
+      # Named extensions rather than a directory glob: the artifact directory also
+      # holds the distro tarball and the test archive, which are hundreds of
+      # megabytes and reproducible from the ref. Everything here is a file the
+      # collect step above chose, so terraform.tfstate cannot reach an artifact.
+      - name: Upload the run
+        if: always()
+        uses: actions/upload-artifact@v7.0.2
+        with:
+          name: e2e-oci-${{ github.run_id }}
+          path: |
+            ${{ runner.temp }}/e2e-oci.log
+            ${{ runner.temp }}/e2e-oci/*.log
+            ${{ runner.temp }}/e2e-oci/verdict.txt
+            ${{ runner.temp }}/e2e-oci/summary.md
+            ${{ runner.temp }}/e2e-oci/*.txt
+            ${{ runner.temp }}/e2e-oci/*.tsv
+            ${{ runner.temp }}/e2e-oci-sweep/*.log
+          retention-days: 14

.github/workflows/e2e-ddil.yml

@@ -1,7 +1,5 @@
 name: E2E DDIL
 
-# This workflow is manually triggered while the DDIL scenarios are being
-# validated.
 on:
   workflow_dispatch:
     inputs:
@@ -10,47 +8,49 @@ on:
         required: false
         default: ""
 
+# Shared with e2e-nightly.yml and e2e-suites.yml: every one of them provisions
+# many cells on the same runner pools and the same hypervisors, so two in
+# flight compete for their disks and their libvirt guests. Queued rather than
+# cancelled — a run in progress is someone's result, not a stale one. e2e.yml
+# is outside the group: one cluster per run is cheap enough to overlap.
+concurrency:
+  group: e2e-hypervisors
+  cancel-in-progress: false
+
 permissions:
   contents: read
-  # actions: read lets the otel-job-id action look up this job's numeric id via
-  # the Actions API — github.job is only the YAML key, no context exposes it.
   actions: read
 
 env:
   GIT_BRANCH: ${{ github.ref_name }}
-  # OTLP export to the central Elastic sink (wattle). Repo variable overrides;
-  # empty string disables telemetry entirely.
   SPINIFEX_OTLP_ENDPOINT: ${{ vars.SPINIFEX_OTLP_ENDPOINT || 'http://192.168.1.13:8200' }}
   SPINIFEX_OTEL_ATTRS: ci.run_id=${{ github.run_id }},ci.workflow=${{ github.workflow }}
 
 jobs:
   ddil:
     name: DDIL Real Multi-Node
-    runs-on: [ self-hosted, ci-multi ]
+    runs-on: [self-hosted, ci-multi]
     timeout-minutes: 60
     env:
       TOFU_LOG: /tmp/e2e-tofu-ddil-${{ github.run_id }}.log
-      # Job-level env wins over the workflow-level default. ci.cell=ddil marks
-      # this workflow's telemetry so a DDIL run's partition-induced errors are
-      # never mistaken for a healthy multi-node run's in the sink.
       SPINIFEX_OTEL_ATTRS: ci.run_id=${{ github.run_id }},ci.workflow=${{ github.workflow }},ci.cell=ddil
     steps:
       - name: Clean Workspace
         run: sudo rm -rf "$GITHUB_WORKSPACE"/*
 
-      - uses: actions/create-github-app-token@v3
+      - uses: actions/create-github-app-token@v3.3.0
         id: app-token
         with:
           client-id: ${{ secrets.APP_ID }}
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
           repositories: mulga
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         name: Checkout Spinifex
         with:
           path: spinifex
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         name: Checkout Mulga (tofu-cluster)
         with:
           repository: mulgadc/mulga
@@ -81,7 +81,7 @@ jobs:
       # Adds ci.job_id alongside ci.cell, before Bootstrap bakes the attrs into
       # the VMs, so a telemetry doc points back at this job's log directly.
       - name: Resolve CI job id
-        uses: ./spinifex/.github/actions/otel-job-id
+        uses: $/.github/actions/otel-job-id
         with:
           job-name: DDIL Real Multi-Node
 
@@ -103,7 +103,7 @@ jobs:
           quiet_run "tofu workspace select"    "$TOFU_LOG" tofu workspace select -or-create "${SPINIFEX_CI_ENV}"
           quiet_run "tofu destroy (pre-clean)" "$TOFU_LOG" tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false || true
           quiet_run "scrub-env (pre-clean)"    "$TOFU_LOG" ./scrub-env.sh "${SPINIFEX_CI_ENV}" || true
-          quiet_run "tofu apply"               "$TOFU_LOG" tofu apply -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
+          retry_run "tofu apply"               "$TOFU_LOG" tofu apply -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
           ok "VMs provisioned"
 
       - name: Bootstrap via Binary Install
@@ -175,7 +175,7 @@ jobs:
 
       - name: Publish test summary
         if: always()
-        uses: ./spinifex/.github/actions/junit-report
+        uses: $/.github/actions/junit-report
         with:
           junit-glob: ${{ runner.temp }}/ddil-results/junit-*.xml
           title: "DDIL scenario results"
@@ -185,7 +185,7 @@ jobs:
       - name: Ship test results to Elasticsearch
         if: always()
         continue-on-error: true
-        uses: ./spinifex/.github/actions/junit-to-es
+        uses: $/.github/actions/junit-to-es
         with:
           junit-glob: ${{ runner.temp }}/ddil-results/junit-*.xml
           cell: ddil
@@ -214,7 +214,7 @@ jobs:
 
       - name: Upload DDIL Results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
         with:
           name: ddil-results-${{ github.run_id }}
           path: ${{ runner.temp }}/ddil-results
@@ -228,13 +228,13 @@ jobs:
           source "${GITHUB_WORKSPACE}/spinifex/.github/scripts/ci-fmt.sh"
           quiet_run "tofu workspace select" "$TOFU_LOG" tofu workspace select -or-create "${SPINIFEX_CI_ENV}"
           quiet_run "telemetry flush"       "$TOFU_LOG" timeout 120 ./flush-telemetry.sh "${SPINIFEX_CI_ENV}" || true
-          quiet_run "tofu destroy"          "$TOFU_LOG" tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
+          retry_run "tofu destroy"          "$TOFU_LOG" tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
           quiet_run "scrub-env"             "$TOFU_LOG" ./scrub-env.sh "${SPINIFEX_CI_ENV}" || true
           ok "teardown complete"
 
       - name: Upload tofu log
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
         with:
           name: tofu-log-ddil-${{ github.run_id }}
           path: ${{ env.TOFU_LOG }}

.github/workflows/e2e-suites.yml

@@ -43,18 +43,22 @@ on:
         required: false
         default: ""
 
+# Shared with e2e-nightly.yml and e2e-ddil.yml: every one of them provisions
+# many cells on the same runner pools and the same hypervisors, so two in
+# flight compete for their disks and their libvirt guests. Queued rather than
+# cancelled — a run in progress is someone's result, not a stale one. e2e.yml
+# is outside the group: one cluster per run is cheap enough to overlap.
+concurrency:
+  group: e2e-hypervisors
+  cancel-in-progress: false
+
 permissions:
   contents: read
-  # actions: read lets the otel-job-id action look up a provision job's numeric
-  # id via the Actions API — github.job is only the YAML key, no context
-  # exposes it.
   actions: read
 
 env:
   GIT_BRANCH: ${{ github.ref_name }}
   TEST_RUN: ${{ inputs.test_run || '' }}
-  # OTLP export to the central Elastic sink (wattle). Repo variable overrides;
-  # empty string disables telemetry entirely.
   SPINIFEX_OTLP_ENDPOINT: ${{ vars.SPINIFEX_OTLP_ENDPOINT || 'http://192.168.1.13:8200' }}
   SPINIFEX_OTEL_ATTRS: ci.run_id=${{ github.run_id }},ci.workflow=${{ github.workflow }}
 
@@ -73,12 +77,6 @@ jobs:
       matrix: ${{ steps.suites.outputs.matrix }}
     env:
       TOFU_LOG: /tmp/e2e-tofu-single-${{ github.run_id }}.log
-      # This job (not single_suite) is where "Bootstrap via Binary Install"
-      # bakes SPINIFEX_OTEL_ATTRS into the VM's telemetry.env, before the
-      # suite matrix even exists — single_suite's legs share this one
-      # already-booted VM, so daemon telemetry can't be scoped any finer
-      # than "single env" per suite leg. ci.cell=single distinguishes it
-      # from multi_provision's VMs within the same run id.
       SPINIFEX_OTEL_ATTRS: ci.run_id=${{ github.run_id }},ci.workflow=${{ github.workflow }},ci.cell=single
     steps:
       - name: Reap Orphan Procs
@@ -105,25 +103,25 @@ jobs:
             | sort -r | xargs -r -I{} sudo umount -l -R {} || true
           sudo rm -rf --one-file-system "$GITHUB_WORKSPACE"/*
 
-      - uses: actions/create-github-app-token@v3
+      - uses: actions/create-github-app-token@v3.3.0
         id: app-token
         with:
           client-id: ${{ secrets.APP_ID }}
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
           repositories: mulga
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/mulga
           token: ${{ steps.app-token.outputs.token }}
           sparse-checkout: scripts/tofu-cluster
           path: mulga
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           path: spinifex
 
-      - uses: actions/setup-go@v7
+      - uses: actions/setup-go@v7.0.0
         with:
           go-version-file: spinifex/go.mod
           cache: false
@@ -143,10 +141,9 @@ jobs:
           LIST="${REQUESTED:-${E2E_SUITES_SINGLE}}"
           e2e_suites_assert_subset "single_suites" "${LIST}" "${E2E_SUITES_SINGLE}"
           echo "list=${LIST}" >> "$GITHUB_OUTPUT"
-          # Unquoted on purpose: the space-separated list must word-split into
-          # one JSON element per suite.
-          # shellcheck disable=SC2086
-          JSON=$(printf '%s\n' ${LIST} | jq -R . | jq -cs .)
+          # 45 is the floor this job has always had, so resolving each leg's
+          # budget can only raise it — storagefault and rds ask for more.
+          JSON=$(e2e_suite_matrix "${LIST}" 45)
           echo "matrix=${JSON}" >> "$GITHUB_OUTPUT"
 
       - name: Reclaim docker build cache
@@ -160,7 +157,7 @@ jobs:
       # the env: the suite legs share this env and its baked telemetry.env, so
       # the provisioner is the only job the daemon telemetry can belong to.
       - name: Resolve CI job id
-        uses: ./spinifex/.github/actions/otel-job-id
+        uses: $/.github/actions/otel-job-id
         with:
           job-name: Single env · provision
 
@@ -182,7 +179,7 @@ jobs:
           quiet_run "tofu workspace select"    "$TOFU_LOG" tofu workspace select -or-create "${SPINIFEX_CI_ENV}"
           quiet_run "tofu destroy (pre-clean)" "$TOFU_LOG" tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false || true
           quiet_run "scrub-env (pre-clean)"    "$TOFU_LOG" ./scrub-env.sh "${SPINIFEX_CI_ENV}" || true
-          quiet_run "tofu apply"               "$TOFU_LOG" tofu apply -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
+          retry_run "tofu apply"               "$TOFU_LOG" tofu apply -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
           ok "VM provisioned"
 
       - name: Bootstrap via Binary Install
@@ -303,7 +300,7 @@ jobs:
 
       - name: Upload tofu log
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
         with:
           name: tofu-log-single-${{ github.run_id }}
           path: ${{ env.TOFU_LOG }}
@@ -311,31 +308,34 @@ jobs:
           retention-days: 14
 
   single_suite:
-    name: Single env · suite
+    name: Single env · ${{ matrix.suite }}
     needs: single_provision
     runs-on: [self-hosted, ci-single]
-    timeout-minutes: 45
+    # Per leg, from suite-sets.sh: one number for every suite would have to be
+    # storagefault's, and every other leg would then hang for 105 minutes.
+    timeout-minutes: ${{ matrix.timeout }}
     strategy:
       fail-fast: false
       matrix:
-        suite: ${{ fromJSON(needs.single_provision.outputs.matrix) }}
+        include: ${{ fromJSON(needs.single_provision.outputs.matrix) }}
     env:
       WAN_IP: ${{ needs.single_provision.outputs.wan_ip }}
       SSH_KEY: ${{ needs.single_provision.outputs.ssh_key }}
       ARTIFACT_DIR: /tmp/spinifex-e2e-single-${{ github.run_id }}-${{ matrix.suite }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           path: spinifex
 
-      - uses: actions/setup-go@v7
+      - uses: actions/setup-go@v7.0.0
         with:
           go-version-file: spinifex/go.mod
           cache: false
 
       - name: Install go-junit-report
         run: |
-          go install github.com/jstemmer/go-junit-report/v2@latest
+          # Version from go.mod's tool directive, checked against go.sum.
+          GOWORK=off go -C spinifex install github.com/jstemmer/go-junit-report/v2
           echo "$HOME/go/bin" >> "$GITHUB_PATH"
 
       - name: Run ${{ matrix.suite }}
@@ -343,6 +343,8 @@ jobs:
         run: |
           set +e
           SUITE="${{ matrix.suite }}"
+          . "${GITHUB_WORKSPACE}/spinifex/.github/scripts/suite-sets.sh"
+          TMO="$(e2e_suite_timeout "${SUITE}")"
           VM_HOST="tf-user@${WAN_IP}"
           TEST_RUN_FLAG=""
           [ -n "${TEST_RUN}" ] && TEST_RUN_FLAG="-test.run=${TEST_RUN}"
@@ -360,7 +362,7 @@ jobs:
              GITHUB_ACTIONS=true FORCE_COLOR=1 SPINIFEX_E2E=1 SPINIFEX_MODE=single \
                SPINIFEX_E2E_RUN_ID='${{ github.run_id }}' \
                ARTIFACT_DIR='${ARTIFACT_DIR}' \
-               ./${SUITE}.test -test.v -test.timeout=30m ${TEST_RUN_FLAG} \
+               ./${SUITE}.test -test.v -test.timeout=${TMO} ${TEST_RUN_FLAG} \
                2>&1 | tee '${ARTIFACT_DIR}/test-${SUITE}.log' \
                     | sed -uE 's/^[[:space:]]+([a-zA-Z0-9_]+_test\.go:[0-9]+: )?//'; \
              exit \${PIPESTATUS[0]}"
@@ -389,7 +391,7 @@ jobs:
 
       - name: Publish test summary
         if: always()
-        uses: ./spinifex/.github/actions/junit-report
+        uses: $/.github/actions/junit-report
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           title: "E2E ${{ matrix.suite }} results"
@@ -399,20 +401,20 @@ jobs:
       - name: Ship test results to Elasticsearch
         if: always()
         continue-on-error: true
-        uses: ./spinifex/.github/actions/junit-to-es
+        uses: $/.github/actions/junit-to-es
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           cell: single
 
       - name: Analyze e2e failures
         if: always()
-        uses: ./spinifex/.github/actions/e2e-analyze
+        uses: $/.github/actions/e2e-analyze
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           log-dir: ${{ env.ARTIFACT_DIR }}
           title: "E2E ${{ matrix.suite }} failure analysis"
 
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@v7.0.2
         if: always()
         with:
           name: e2e-single-${{ matrix.suite }}-${{ github.run_id }}
@@ -443,7 +445,7 @@ jobs:
       # Reuse the persisted mulga/ tofu-cluster workspace from single_provision.
       # Re-checkout only spinifex (for ci-fmt + diag scripts); checking out mulga
       # again would wipe the local tofu state and orphan the VM.
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           path: spinifex
 
@@ -466,7 +468,7 @@ jobs:
             | tar -C "${ARTIFACT_DIR}/lb-console" -xf - 2>/dev/null
           true
 
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@v7.0.2
         if: always()
         with:
           name: e2e-single-diag-${{ github.run_id }}
@@ -516,13 +518,13 @@ jobs:
           find "$WS" -name '.terraform.tfstate.lock.info' -delete 2>/dev/null
           quiet_run "tofu workspace select" "$TOFU_LOG" tofu workspace select -or-create "${SPINIFEX_CI_ENV}"
           quiet_run "telemetry flush"       "$TOFU_LOG" timeout 120 ./flush-telemetry.sh "${SPINIFEX_CI_ENV}" || true
-          quiet_run "tofu destroy"          "$TOFU_LOG" timeout 600 tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
+          retry_run "tofu destroy"          "$TOFU_LOG" timeout 600 tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
           quiet_run "scrub-env"             "$TOFU_LOG" ./scrub-env.sh "${SPINIFEX_CI_ENV}"
           ok "teardown complete"
 
       - name: Upload tofu log
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
         with:
           name: tofu-log-single-td-${{ github.run_id }}
           path: ${{ env.TOFU_LOG }}
@@ -570,25 +572,25 @@ jobs:
             | sort -r | xargs -r -I{} sudo umount -l -R {} || true
           sudo rm -rf --one-file-system "$GITHUB_WORKSPACE"/*
 
-      - uses: actions/create-github-app-token@v3
+      - uses: actions/create-github-app-token@v3.3.0
         id: app-token
         with:
           client-id: ${{ secrets.APP_ID }}
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
           repositories: mulga
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/mulga
           token: ${{ steps.app-token.outputs.token }}
           sparse-checkout: scripts/tofu-cluster
           path: mulga
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           path: spinifex
 
-      - uses: actions/setup-go@v7
+      - uses: actions/setup-go@v7.0.0
         with:
           go-version-file: spinifex/go.mod
           cache: false
@@ -605,7 +607,7 @@ jobs:
 
       # See the matching note on single_provision.
       - name: Resolve CI job id
-        uses: ./spinifex/.github/actions/otel-job-id
+        uses: $/.github/actions/otel-job-id
         with:
           job-name: Multi env · provision
 
@@ -627,7 +629,7 @@ jobs:
           quiet_run "tofu workspace select"    "$TOFU_LOG" tofu workspace select -or-create "${SPINIFEX_CI_ENV}"
           quiet_run "tofu destroy (pre-clean)" "$TOFU_LOG" tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false || true
           quiet_run "scrub-env (pre-clean)"    "$TOFU_LOG" ./scrub-env.sh "${SPINIFEX_CI_ENV}" || true
-          quiet_run "tofu apply"               "$TOFU_LOG" tofu apply -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
+          retry_run "tofu apply"               "$TOFU_LOG" tofu apply -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
           ok "3-node cluster provisioned"
 
       - name: Bootstrap via Binary Install
@@ -669,10 +671,9 @@ jobs:
           LIST="${REQUESTED:-${E2E_SUITES_MULTI}}"
           e2e_suites_assert_subset "multi_suites" "${LIST}" "${E2E_SUITES_MULTI}"
           echo "list=${LIST}" >> "$GITHUB_OUTPUT"
-          # Unquoted on purpose: the space-separated list must word-split into
-          # one JSON element per suite.
-          # shellcheck disable=SC2086
-          JSON=$(printf '%s\n' ${LIST} | jq -R . | jq -cs .)
+          # 60 is the floor this job has always had; multi-node legs carry a
+          # heavier setup than single-node ones, which is why it is higher.
+          JSON=$(e2e_suite_matrix "${LIST}" 60)
           echo "matrix=${JSON}" >> "$GITHUB_OUTPUT"
 
       - name: Build multinode binaries on runner
@@ -714,7 +715,7 @@ jobs:
 
       - name: Upload tofu log
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
         with:
           name: tofu-log-multi-${{ github.run_id }}
           path: ${{ env.TOFU_LOG }}
@@ -722,32 +723,34 @@ jobs:
           retention-days: 14
 
   multi_suite:
-    name: Multi env · suite
+    name: Multi env · ${{ matrix.suite }}
     needs: multi_provision
     runs-on: [self-hosted, ci-multi]
-    timeout-minutes: 60
+    # See the note on single_suite: the budget is the suite's, not the job's.
+    timeout-minutes: ${{ matrix.timeout }}
     strategy:
       fail-fast: false
       matrix:
-        suite: ${{ fromJSON(needs.multi_provision.outputs.matrix) }}
+        include: ${{ fromJSON(needs.multi_provision.outputs.matrix) }}
     env:
       NODE1_IP: ${{ needs.multi_provision.outputs.node1_ip }}
       SSH_KEY: ${{ needs.multi_provision.outputs.ssh_key }}
       NODES_CSV: ${{ needs.multi_provision.outputs.nodes_csv }}
       ARTIFACT_DIR: /tmp/spinifex-e2e-multi-${{ github.run_id }}-${{ matrix.suite }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           path: spinifex
 
-      - uses: actions/setup-go@v7
+      - uses: actions/setup-go@v7.0.0
         with:
           go-version-file: spinifex/go.mod
           cache: false
 
       - name: Install go-junit-report
         run: |
-          go install github.com/jstemmer/go-junit-report/v2@latest
+          # Version from go.mod's tool directive, checked against go.sum.
+          GOWORK=off go -C spinifex install github.com/jstemmer/go-junit-report/v2
           echo "$HOME/go/bin" >> "$GITHUB_PATH"
 
       - name: Run ${{ matrix.suite }}
@@ -755,6 +758,8 @@ jobs:
         run: |
           set +e
           SUITE="${{ matrix.suite }}"
+          . "${GITHUB_WORKSPACE}/spinifex/.github/scripts/suite-sets.sh"
+          TMO="$(e2e_suite_timeout "${SUITE}")"
           VM_HOST="tf-user@${NODE1_IP}"
           TEST_RUN_FLAG=""
           [ -n "${TEST_RUN}" ] && TEST_RUN_FLAG="-test.run=${TEST_RUN}"
@@ -773,7 +778,7 @@ jobs:
                SPINIFEX_NODES='${NODES_CSV}' SPINIFEX_NODE_IPS='${NODES_CSV}' \
                SPINIFEX_SSH_USER=tf-user SPINIFEX_SSH_KEY=\$HOME/.ssh/tf-user-ap-southeast-2 \
                ARTIFACT_DIR='${ARTIFACT_DIR}' \
-               ./${SUITE}.test -test.v -test.timeout=30m ${TEST_RUN_FLAG} \
+               ./${SUITE}.test -test.v -test.timeout=${TMO} ${TEST_RUN_FLAG} \
                2>&1 | tee '${ARTIFACT_DIR}/test-${SUITE}.log' \
                     | sed -uE 's/^[[:space:]]+([a-zA-Z0-9_]+_test\.go:[0-9]+: )?//'; \
              exit \${PIPESTATUS[0]}"
@@ -801,7 +806,7 @@ jobs:
 
       - name: Publish test summary
         if: always()
-        uses: ./spinifex/.github/actions/junit-report
+        uses: $/.github/actions/junit-report
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           title: "Multi-Node E2E ${{ matrix.suite }} results"
@@ -811,20 +816,20 @@ jobs:
       - name: Ship test results to Elasticsearch
         if: always()
         continue-on-error: true
-        uses: ./spinifex/.github/actions/junit-to-es
+        uses: $/.github/actions/junit-to-es
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           cell: multi
 
       - name: Analyze e2e failures
         if: always()
-        uses: ./spinifex/.github/actions/e2e-analyze
+        uses: $/.github/actions/e2e-analyze
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           log-dir: ${{ env.ARTIFACT_DIR }}
           title: "Multi-Node E2E ${{ matrix.suite }} failure analysis"
 
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@v7.0.2
         if: always()
         with:
           name: e2e-multi-${{ matrix.suite }}-${{ github.run_id }}
@@ -851,7 +856,7 @@ jobs:
       SSH_KEY: ${{ needs.multi_provision.outputs.ssh_key }}
       NODES_CSV: ${{ needs.multi_provision.outputs.nodes_csv }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           path: spinifex
 
@@ -899,13 +904,13 @@ jobs:
           find "$WS" -name '.terraform.tfstate.lock.info' -delete 2>/dev/null
           quiet_run "tofu workspace select" "$TOFU_LOG" tofu workspace select -or-create "${SPINIFEX_CI_ENV}"
           quiet_run "telemetry flush"       "$TOFU_LOG" timeout 120 ./flush-telemetry.sh "${SPINIFEX_CI_ENV}" || true
-          quiet_run "tofu destroy"          "$TOFU_LOG" timeout 600 tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
+          retry_run "tofu destroy"          "$TOFU_LOG" timeout 600 tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
           quiet_run "scrub-env"             "$TOFU_LOG" ./scrub-env.sh "${SPINIFEX_CI_ENV}"
           ok "teardown complete"
 
       - name: Upload tofu log
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
         with:
           name: tofu-log-multi-td-${{ github.run_id }}
           path: ${{ env.TOFU_LOG }}

.github/workflows/e2e.yml

@@ -7,6 +7,7 @@ on:
       - dev
     paths:
       - "**/*.go"
+      - "!**/*_test.go"
       - go.mod
       - go.sum
       - Makefile
@@ -26,20 +27,67 @@ on:
 permissions:
   contents: read
   statuses: write
-  # actions: read lets the otel-job-id action look up a job's numeric id via
-  # the Actions API — github.job is only the YAML key, no context exposes it.
   actions: read
 
 env:
   GIT_BRANCH: ${{ github.ref_name }}
   SUITES: ${{ inputs.suites || 'e2e-single e2e-multinode e2e-cert e2e-lb e2e-iam e2e-partialblock' }}
   TEST_RUN: ${{ inputs.test_run || '' }}
-  # OTLP export to the central Elastic sink (wattle). Repo variable overrides;
-  # empty string disables telemetry entirely.
   SPINIFEX_OTLP_ENDPOINT: ${{ vars.SPINIFEX_OTLP_ENDPOINT || 'http://192.168.1.13:8200' }}
   SPINIFEX_OTEL_ATTRS: ci.run_id=${{ github.run_id }},ci.workflow=${{ github.workflow }}
 
 jobs:
+  # The inner timeout must fire before the outer one. `go test` reports where it
+  # stopped and the suite's own failure; a job cancelled on timeout reports only
+  # "The operation was canceled" and takes the artifacts with it.
+  #
+  # A job budget cannot be a literal here because the suite set is a dispatch
+  # input: storagefault asks for 90m and diskperf for 180m, both eligible on one
+  # node, so any fixed number is either wrong for them or wasteful for everyone
+  # else. Resolving it from suite-sets.sh keeps the one source of truth and
+  # leaves the default push set at exactly the 60m it has always had.
+  plan:
+    name: Resolve Job Budgets
+    runs-on: ubuntu-26.04
+    timeout-minutes: 5
+    outputs:
+      single_timeout: ${{ steps.budgets.outputs.single_timeout }}
+      multi_timeout: ${{ steps.budgets.outputs.multi_timeout }}
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          path: spinifex
+          sparse-checkout: .github/scripts
+
+      - name: Resolve Budgets
+        id: budgets
+        env:
+          # Provision, install and teardown around the suites, plus the headroom
+          # a multi-suite job needs for whatever ran before the one that hangs.
+          SETUP_ALLOWANCE_MIN: 15
+          # What the job has always had. Kept as a floor so resolving the budget
+          # can only ever raise it, never quietly shorten an existing run.
+          FLOOR_MIN: 60
+        run: |
+          . "${GITHUB_WORKSPACE}/spinifex/.github/scripts/suite-sets.sh"
+          # Only max() is a sound bound: the suites share one job, so a sum would
+          # demand hours for a set that has never taken them. Max is what makes
+          # the hanging suite panic on its own timeout first, which is the point.
+          budget() {
+            local want="${FLOOR_MIN}" s t
+            for s in $(echo "${SUITES}" | sed 's/e2e-//g' | tr ' ' '\n' | grep -xE "$1"); do
+              t="$(e2e_suite_timeout "${s}")"
+              t=$(( ${t%m} + SETUP_ALLOWANCE_MIN ))
+              [ "${t}" -gt "${want}" ] && want="${t}"
+            done
+            echo "${want}"
+          }
+          single=$(budget "${E2E_SUITES_SINGLE_RE}")
+          multi=$(budget "${E2E_SUITES_MULTI_RE}")
+          echo "single_timeout=${single}" >> "$GITHUB_OUTPUT"
+          echo "multi_timeout=${multi}" >> "$GITHUB_OUTPUT"
+          echo "suites='${SUITES}' -> single ${single}m, multi ${multi}m"
+
   e2e_single:
     name: Single-Node E2E
     # The dispatch check gates on exactly the suites this job's Run step
@@ -51,8 +99,9 @@ jobs:
     # tear down. Push triggers keep running via the null-check on
     # inputs.suites.
     if: github.event_name != 'workflow_dispatch' || contains(github.event.inputs.suites, 'e2e-single') || contains(github.event.inputs.suites, 'e2e-iam') || contains(github.event.inputs.suites, 'e2e-cert') || contains(github.event.inputs.suites, 'e2e-eks') || contains(github.event.inputs.suites, 'e2e-ecs') || contains(github.event.inputs.suites, 'e2e-storagegrowth') || contains(github.event.inputs.suites, 'e2e-partialblock') || contains(github.event.inputs.suites, 'e2e-rds')
+    needs: plan
     runs-on: [self-hosted, ci-single]
-    timeout-minutes: 60
+    timeout-minutes: ${{ fromJSON(needs.plan.outputs.single_timeout) }}
     env:
       TOFU_LOG: /tmp/e2e-tofu-single-${{ github.run_id }}.log
       ARTIFACT_DIR: /tmp/spinifex-e2e-artifacts-${{ github.run_id }}
@@ -93,25 +142,25 @@ jobs:
           # stale suite-status.txt / analysis dirs can't leak into this attempt.
           rm -rf "${ARTIFACT_DIR}"
 
-      - uses: actions/create-github-app-token@v3
+      - uses: actions/create-github-app-token@v3.3.0
         id: app-token
         with:
           client-id: ${{ secrets.APP_ID }}
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
           repositories: mulga
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/mulga
           token: ${{ steps.app-token.outputs.token }}
           sparse-checkout: scripts/tofu-cluster
           path: mulga
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           path: spinifex
 
-      - uses: actions/setup-go@v7
+      - uses: actions/setup-go@v7.0.0
         with:
           go-version-file: spinifex/go.mod
           cache: false
@@ -129,7 +178,7 @@ jobs:
       # Adds ci.job_id alongside ci.cell, before Bootstrap bakes the attrs into
       # the VM, so a telemetry doc points back at this job's log directly.
       - name: Resolve CI job id
-        uses: ./spinifex/.github/actions/otel-job-id
+        uses: $/.github/actions/otel-job-id
         with:
           job-name: Single-Node E2E
 
@@ -152,7 +201,7 @@ jobs:
           quiet_run "tofu workspace select"    "$TOFU_LOG" tofu workspace select -or-create "${SPINIFEX_CI_ENV}"
           quiet_run "tofu destroy (pre-clean)" "$TOFU_LOG" tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false || true
           quiet_run "scrub-env (pre-clean)"    "$TOFU_LOG" ./scrub-env.sh "${SPINIFEX_CI_ENV}" || true
-          quiet_run "tofu apply"               "$TOFU_LOG" tofu apply -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
+          retry_run "tofu apply"               "$TOFU_LOG" tofu apply -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
           ok "VM provisioned"
 
       - name: Bootstrap via Binary Install
@@ -323,7 +372,8 @@ jobs:
 
       - name: Install go-junit-report on runner
         run: |
-          go install github.com/jstemmer/go-junit-report/v2@latest
+          # Version from go.mod's tool directive, checked against go.sum.
+          GOWORK=off go -C spinifex install github.com/jstemmer/go-junit-report/v2
           echo "$HOME/go/bin" >> "$GITHUB_PATH"
 
       - name: Ship test binaries to VM
@@ -357,6 +407,10 @@ jobs:
           # suite-sets.sh also carries the per-suite rationale.
           . "${GITHUB_WORKSPACE}/spinifex/.github/scripts/suite-sets.sh"
           SUITES_RUN=$(echo "${SUITES}" | sed 's/e2e-//g' | tr ' ' '\n' | grep -xE "${E2E_SUITES_SINGLE_RE}" | tr '\n' ' ')
+          # Resolve each suite's timeout here, where suite-sets.sh is readable, and
+          # carry the pairs into the remote loop below — the VM has no checkout.
+          SUITE_TMOS=""
+          for s in ${SUITES_RUN}; do SUITE_TMOS="${SUITE_TMOS}${s}:$(e2e_suite_timeout "${s}") "; done
           if [ -z "$(echo "${SUITES_RUN}" | tr -d ' ')" ]; then
             echo "no in-VM suites requested (SUITES=${SUITES}); skipping"
             echo "rc=0" >> "$GITHUB_OUTPUT"
@@ -388,7 +442,7 @@ jobs:
                echo \"::group::suite \$SUITE\"; \
                printf '\n%s%s━━ suite %s ━━%s\n' \"\$B\" \"\$C\" \"\$SUITE\" \"\$R\"; \
                date -u +%Y-%m-%dT%H:%M:%SZ > '${ARTIFACT_DIR}/test-'\$SUITE'.start'; \
-               case \$SUITE in rds) TMO=50m ;; *) TMO=30m ;; esac; \
+               TMO=30m; for kv in ${SUITE_TMOS}; do case \$kv in \$SUITE:*) TMO=\${kv#*:} ;; esac; done; \
                GITHUB_ACTIONS=true FORCE_COLOR=1 SPINIFEX_E2E=1 SPINIFEX_MODE=single \
                  ARTIFACT_DIR='${ARTIFACT_DIR}' \
                  ./\$SUITE.test -test.v -test.timeout=\$TMO ${TEST_RUN_FLAG} \
@@ -459,7 +513,7 @@ jobs:
 
       - name: Publish test summary
         if: always()
-        uses: ./spinifex/.github/actions/junit-report
+        uses: $/.github/actions/junit-report
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           title: "E2E results"
@@ -469,20 +523,20 @@ jobs:
       - name: Ship test results to Elasticsearch
         if: always()
         continue-on-error: true
-        uses: ./spinifex/.github/actions/junit-to-es
+        uses: $/.github/actions/junit-to-es
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           cell: single
 
       - name: Analyze e2e failures
         if: always()
-        uses: ./spinifex/.github/actions/e2e-analyze
+        uses: $/.github/actions/e2e-analyze
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           log-dir: ${{ env.ARTIFACT_DIR }}
           title: "E2E failure analysis"
 
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@v7.0.2
         if: always()
         with:
           name: e2e-artifacts-${{ github.run_id }}
@@ -520,13 +574,13 @@ jobs:
           find "$WS" -name '.terraform.tfstate.lock.info' -delete 2>/dev/null
           quiet_run "tofu workspace select" "$TOFU_LOG" tofu workspace select -or-create "${SPINIFEX_CI_ENV}"
           quiet_run "telemetry flush"       "$TOFU_LOG" timeout 120 ./flush-telemetry.sh "${SPINIFEX_CI_ENV}" || true
-          quiet_run "tofu destroy"          "$TOFU_LOG" timeout 600 tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
+          retry_run "tofu destroy"          "$TOFU_LOG" timeout 600 tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
           quiet_run "scrub-env"             "$TOFU_LOG" ./scrub-env.sh "${SPINIFEX_CI_ENV}"
           ok "teardown complete"
 
       - name: Upload tofu log
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
         with:
           name: tofu-log-single-${{ github.run_id }}
           path: ${{ env.TOFU_LOG }}
@@ -549,8 +603,9 @@ jobs:
     # provisions the 3-node env when requested on its own, and the env stays
     # unprovisioned when none of them are asked for.
     if: github.event_name != 'workflow_dispatch' || contains(github.event.inputs.suites, 'e2e-multinode') || contains(github.event.inputs.suites, 'e2e-lb') || contains(github.event.inputs.suites, 'e2e-cert')
+    needs: plan
     runs-on: [self-hosted, ci-multi]
-    timeout-minutes: 60
+    timeout-minutes: ${{ fromJSON(needs.plan.outputs.multi_timeout) }}
     env:
       TOFU_LOG: /tmp/e2e-tofu-multi-${{ github.run_id }}.log
       ARTIFACT_DIR: /tmp/spinifex-e2e-multi-artifacts-${{ github.run_id }}
@@ -588,25 +643,25 @@ jobs:
           # stale suite-status.txt / analysis dirs can't leak into this attempt.
           rm -rf "${ARTIFACT_DIR}"
 
-      - uses: actions/create-github-app-token@v3
+      - uses: actions/create-github-app-token@v3.3.0
         id: app-token
         with:
           client-id: ${{ secrets.APP_ID }}
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
           repositories: mulga
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/mulga
           token: ${{ steps.app-token.outputs.token }}
           sparse-checkout: scripts/tofu-cluster
           path: mulga
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           path: spinifex
 
-      - uses: actions/setup-go@v7
+      - uses: actions/setup-go@v7.0.0
         with:
           go-version-file: spinifex/go.mod
           cache: false
@@ -623,7 +678,7 @@ jobs:
 
       # See the matching note on e2e_single.
       - name: Resolve CI job id
-        uses: ./spinifex/.github/actions/otel-job-id
+        uses: $/.github/actions/otel-job-id
         with:
           job-name: Multi-Node E2E
 
@@ -646,7 +701,7 @@ jobs:
           quiet_run "tofu workspace select"    "$TOFU_LOG" tofu workspace select -or-create "${SPINIFEX_CI_ENV}"
           quiet_run "tofu destroy (pre-clean)" "$TOFU_LOG" tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false || true
           quiet_run "scrub-env (pre-clean)"    "$TOFU_LOG" ./scrub-env.sh "${SPINIFEX_CI_ENV}" || true
-          quiet_run "tofu apply"               "$TOFU_LOG" tofu apply -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
+          retry_run "tofu apply"               "$TOFU_LOG" tofu apply -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
           ok "3-node cluster provisioned"
 
       - name: Bootstrap via Binary Install
@@ -704,7 +759,8 @@ jobs:
 
       - name: Install go-junit-report on runner
         run: |
-          go install github.com/jstemmer/go-junit-report/v2@latest
+          # Version from go.mod's tool directive, checked against go.sum.
+          GOWORK=off go -C spinifex install github.com/jstemmer/go-junit-report/v2
           echo "$HOME/go/bin" >> "$GITHUB_PATH"
 
       - name: Ship test binaries to node1
@@ -772,6 +828,8 @@ jobs:
           # Allow-list, not a deny-list — see the single-node job for why.
           . "${GITHUB_WORKSPACE}/spinifex/.github/scripts/suite-sets.sh"
           SUITES_RUN=$(echo "${SUITES}" | sed 's/e2e-//g' | tr ' ' '\n' | grep -xE "${E2E_SUITES_MULTI_RE}" | tr '\n' ' ')
+          SUITE_TMOS=""
+          for s in ${SUITES_RUN}; do SUITE_TMOS="${SUITE_TMOS}${s}:$(e2e_suite_timeout "${s}") "; done
           if [ -z "$(echo "${SUITES_RUN}" | tr -d ' ')" ]; then
             echo "no multinode-eligible suites requested (SUITES=${SUITES}); skipping"
             echo "rc=0" >> "$GITHUB_OUTPUT"
@@ -803,13 +861,14 @@ jobs:
                echo \"::group::suite \$SUITE\"; \
                printf '\n%s%s━━ suite %s ━━%s\n' \"\$B\" \"\$C\" \"\$SUITE\" \"\$R\"; \
                date -u +%Y-%m-%dT%H:%M:%SZ > '${ARTIFACT_DIR}/test-'\$SUITE'.start'; \
+               TMO=30m; for kv in ${SUITE_TMOS}; do case \$kv in \$SUITE:*) TMO=\${kv#*:} ;; esac; done; \
                GITHUB_ACTIONS=true FORCE_COLOR=1 SPINIFEX_E2E=1 SPINIFEX_MODE=multinode \
                  SPINIFEX_NODES='${NODES_CSV}' \
                  SPINIFEX_NODE_IPS='${NODES_CSV}' \
                  SPINIFEX_SSH_USER=tf-user \
                  SPINIFEX_SSH_KEY=\$HOME/.ssh/tf-user-ap-southeast-2 \
                  ARTIFACT_DIR='${ARTIFACT_DIR}' \
-                 ./\$SUITE.test -test.v -test.timeout=30m ${TEST_RUN_FLAG} \
+                 ./\$SUITE.test -test.v -test.timeout=\$TMO ${TEST_RUN_FLAG} \
                  2>&1 | tee '${ARTIFACT_DIR}/test-'\$SUITE'.log' \
                       | sed -uE 's/^[[:space:]]+([a-zA-Z0-9_]+_test\.go:[0-9]+: )?//'; \
                rc=\${PIPESTATUS[0]}; \
@@ -908,7 +967,7 @@ jobs:
 
       - name: Publish test summary
         if: always()
-        uses: ./spinifex/.github/actions/junit-report
+        uses: $/.github/actions/junit-report
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           title: "Multi-Node E2E results"
@@ -918,20 +977,20 @@ jobs:
       - name: Ship test results to Elasticsearch
         if: always()
         continue-on-error: true
-        uses: ./spinifex/.github/actions/junit-to-es
+        uses: $/.github/actions/junit-to-es
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           cell: multi
 
       - name: Analyze e2e failures
         if: always()
-        uses: ./spinifex/.github/actions/e2e-analyze
+        uses: $/.github/actions/e2e-analyze
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           log-dir: ${{ env.ARTIFACT_DIR }}
           title: "Multi-Node E2E failure analysis"
 
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@v7.0.2
         if: always()
         with:
           name: e2e-multi-artifacts-${{ github.run_id }}
@@ -972,13 +1031,13 @@ jobs:
           find "$WS" -name '.terraform.tfstate.lock.info' -delete 2>/dev/null
           quiet_run "tofu workspace select" "$TOFU_LOG" tofu workspace select -or-create "${SPINIFEX_CI_ENV}"
           quiet_run "telemetry flush"       "$TOFU_LOG" timeout 120 ./flush-telemetry.sh "${SPINIFEX_CI_ENV}" || true
-          quiet_run "tofu destroy"          "$TOFU_LOG" timeout 600 tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
+          retry_run "tofu destroy"          "$TOFU_LOG" timeout 600 tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
           quiet_run "scrub-env"             "$TOFU_LOG" ./scrub-env.sh "${SPINIFEX_CI_ENV}"
           ok "teardown complete"
 
       - name: Upload tofu log
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
         with:
           name: tofu-log-multi-${{ github.run_id }}
           path: ${{ env.TOFU_LOG }}
@@ -1048,14 +1107,14 @@ jobs:
       # the aggregation script below treats an absent suite-status.txt as
       # "no failures from that leg".
       - name: Download single-node artifacts
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@v8.0.2
         continue-on-error: true
         with:
           name: e2e-artifacts-${{ github.run_id }}
           path: ${{ github.workspace }}/es-summary-single
 
       - name: Download multi-node artifacts
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@v8.0.2
         continue-on-error: true
         with:
           name: e2e-multi-artifacts-${{ github.run_id }}

.github/workflows/gpu-e2e.yml

@@ -56,15 +56,7 @@ concurrency:
   cancel-in-progress: false
 
 env:
-  # OTLP export to the central Elastic sink (wattle is the sink itself — see
-  # Part A.2). Repo variable overrides; carried for correlation even though
-  # the GPU suite's own daemon-side spans are emitted by wattle's already-
-  # configured obs-agent, not by this job.
   SPINIFEX_OTLP_ENDPOINT: ${{ vars.SPINIFEX_OTLP_ENDPOINT || 'http://192.168.1.13:8200' }}
-  # ci.cell=gpu keeps this workflow's telemetry separable from the tofu-env
-  # workflows'. Nothing in this job bakes these attrs into a daemon (see the
-  # note above), so the label only takes effect once wattle's obs-agent is
-  # given them; there is deliberately no ci.job_id lookup for the same reason.
   SPINIFEX_OTEL_ATTRS: ci.run_id=${{ github.run_id }},ci.workflow=${{ github.workflow }},ci.cell=gpu
   WATTLE_SSH_HOST: ${{ vars.WATTLE_SSH_HOST || '192.168.1.13' }}
   WATTLE_SSH_USER: ${{ vars.WATTLE_SSH_USER || 'tf-user' }}
@@ -78,8 +70,6 @@ jobs:
     env:
       ARTIFACT_DIR: /tmp/spinifex-gpu-e2e-artifacts-${{ github.run_id }}
     steps:
-      # Manual-work mutex gate — see setup note 4 above. Checked BEFORE any
-      # SSH to wattle so a paused run touches the box zero times.
       - name: Manual-work mutex gate
         id: gate
         env:
@@ -105,10 +95,10 @@ jobs:
         if: steps.gate.outputs.paused != 'true'
         run: sudo rm -rf --one-file-system "$GITHUB_WORKSPACE"/*
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         if: steps.gate.outputs.paused != 'true'
 
-      - uses: actions/setup-go@v7
+      - uses: actions/setup-go@v7.0.0
         if: steps.gate.outputs.paused != 'true'
         with:
           go-version-file: go.mod
@@ -122,8 +112,6 @@ jobs:
           echo "${{ secrets.WATTLE_SSH_KEY }}" > "${RUNNER_TEMP}/wattle-ci"
           echo "ssh_opts=-o StrictHostKeyChecking=no -o ConnectTimeout=10 -i ${RUNNER_TEMP}/wattle-ci" >> "$GITHUB_ENV"
 
-      # Healthcheck: confirm wattle's persistent AWS-compat control plane is
-      # actually up before spending time building/shipping the test binary.
       - name: Healthcheck — describe-regions
         if: steps.gate.outputs.paused != 'true'
         run: |
@@ -131,18 +119,6 @@ jobs:
           ssh ${{ env.ssh_opts }} "${WATTLE_SSH_USER}@${WATTLE_SSH_HOST}" \
             'AWS_PROFILE=spinifex aws ec2 describe-regions --output text'
 
-      # Ensure the base EC2 GPU AMI is present — the raw-EC2 GPU passthrough
-      # test is the always-on baseline, so CI self-provisions it rather than
-      # depending on a manual import. `--name` selects the catalog entry (pulls
-      # the prebuilt image from iso.mulgadc.com); `--ami-name` is REQUIRED to
-      # name the AMI ubuntu-26.04-nvidia-gpu-x86_64 — without it the import
-      # falls back to the generic ami-<distro>-<version>-<arch>, which the
-      # tests/e2e/gpu filter would never match. Idempotent — skipped once
-      # wattle's persistent loop-fs already has the named AMI (the 4.4G source
-      # qcow2 is cached in the images dir, so a re-import wouldn't re-download).
-      # `spx admin images import` writes local spinifex storage, so it needs
-      # the `spinifex` group active (sg); aws-CLI calls hit the gateway over
-      # HTTPS and don't.
       - name: Ensure base GPU AMI present (import-if-absent)
         if: steps.gate.outputs.paused != 'true'
         run: |
@@ -171,11 +147,6 @@ jobs:
           '
           ssh ${{ env.ssh_opts }} "${WATTLE_SSH_USER}@${WATTLE_SSH_HOST}" "$REMOTE"
 
-      # Preflight — the base GPU AMI is REQUIRED: the setup step above just
-      # ensured it, so a miss here means the import silently failed. Hard-fail
-      # rather than run a false-green all-skipped suite. ECS/EKS node AMIs are
-      # opt-in tiers (heavier — node AMIs + cluster spin-up); their tests
-      # self-skip when absent, so only warn.
       - name: Preflight — verify GPU AMIs
         if: steps.gate.outputs.paused != 'true'
         run: |
@@ -205,10 +176,6 @@ jobs:
           '
           ssh ${{ env.ssh_opts }} "${WATTLE_SSH_USER}@${WATTLE_SSH_HOST}" "$REMOTE"
 
-      # Same build command CI's other e2e workflows use to cross-compile a
-      # suite into a shippable binary (tests/e2e/Makefile e2e-build target,
-      # SUITES_BUILD scoped to just gpu). Building on the runner keeps go
-      # toolchain / module cache off wattle entirely.
       - name: Build GPU e2e test binary on runner
         if: steps.gate.outputs.paused != 'true'
         working-directory: tests/e2e
@@ -220,7 +187,8 @@ jobs:
       - name: Install go-junit-report on runner
         if: steps.gate.outputs.paused != 'true'
         run: |
-          go install github.com/jstemmer/go-junit-report/v2@latest
+          # Version from go.mod's tool directive, checked against go.sum.
+          GOWORK=off go install github.com/jstemmer/go-junit-report/v2
           echo "$HOME/go/bin" >> "$GITHUB_PATH"
 
       - name: Ship GPU e2e test binary to wattle
@@ -231,12 +199,6 @@ jobs:
           ssh ${{ env.ssh_opts }} "$VM" "mkdir -p \$HOME/spinifex-gpu-e2e-bin"
           scp ${{ env.ssh_opts }} tests/e2e/_bin/gpu.test "$VM":spinifex-gpu-e2e-bin/gpu.test
 
-      # Same invocation shape e2e.yml uses to run a pre-built suite binary
-      # (SPINIFEX_E2E=1 SPINIFEX_MODE=single, ./<suite>.test -test.v
-      # -test.timeout=NNm), plus SPINIFEX_WAN_IP: wattle's ~24 bridges make
-      # net.InterfaceAddrs() enumeration pick a co-tenant bridge instead of
-      # the advertised gateway, so the override is required here. The harness
-      # should prefer spinifex.toml's advertised bridge.
       - name: Run GPU e2e suite on wattle
         id: e2e
         if: steps.gate.outputs.paused != 'true'
@@ -282,30 +244,28 @@ jobs:
 
       - name: Publish test summary
         if: always() && steps.gate.outputs.paused != 'true'
-        uses: ./.github/actions/junit-report
+        uses: $/.github/actions/junit-report
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           title: "GPU E2E results"
 
-      # Tolerated on failure: the sink being unreachable must not turn a
-      # green test run red.
       - name: Ship test results to Elasticsearch
         if: always() && steps.gate.outputs.paused != 'true'
         continue-on-error: true
-        uses: ./.github/actions/junit-to-es
+        uses: $/.github/actions/junit-to-es
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           cell: gpu
 
       - name: Analyze e2e failures
         if: always() && steps.gate.outputs.paused != 'true'
-        uses: ./.github/actions/e2e-analyze
+        uses: $/.github/actions/e2e-analyze
         with:
           junit-glob: ${{ env.ARTIFACT_DIR }}/junit-*.xml
           log-dir: ${{ env.ARTIFACT_DIR }}
           title: "GPU E2E failure analysis"
 
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@v7.0.2
         if: always() && steps.gate.outputs.paused != 'true'
         with:
           name: gpu-e2e-artifacts-${{ github.run_id }}
@@ -313,14 +273,6 @@ jobs:
           if-no-files-found: warn
           retention-days: 14
 
-      # Cleanup is NEVER a host teardown: it never runs setup-ovn.sh,
-      # dev-reset, or cluster-reset. It only reconciles EC2-API-level state —
-      # terminate any GPU-typed instance still pending/running (the Go
-      # suite's own t.Cleanup already does this on normal pass/fail exit;
-      # this is the backstop for a hard `-test.timeout` kill or a workflow
-      # cancellation, which skip deferred Go cleanups). Termination triggers
-      # gpuManager.Release() on wattle, returning the A1000 to the pool for
-      # the next queued run or manual test.
       - name: Cleanup — terminate leftover GPU instances, release GPU
         if: always() && steps.gate.outputs.paused != 'true'
         run: |

.github/workflows/image-scripts.yml

@@ -1,9 +1,5 @@
 name: Image Scripts
 
-# Separate from spinifex.yml on purpose: scripts/images/ and images/ are shell
-# and mkosi assets baked into system images, not Go, so they get their own
-# path-filtered gate instead of running on every Go contributor's push (see
-# ui.yml for the same pattern applied to the frontend).
 on:
   push:
     branches:
@@ -33,7 +29,32 @@ jobs:
 
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
 
       - name: Run image script tests + shellcheck
         run: make test-images
+
+  eks_mkosi_image:
+    name: Build mkosi EKS image
+    # A fork PR's code must never run on a persistent self-hosted runner: it
+    # shares disk, caches and credentials with the release jobs.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: [self-hosted, ci-single]
+    concurrency:
+      group: eks-mkosi-image-${{ github.ref }}
+      cancel-in-progress: true
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up Go
+        uses: actions/setup-go@v7.0.0
+        with:
+          go-version-file: "go.mod"
+          # Self-hosted: the module + build cache already persists on local
+          # disk, and cache-save would re-upload hundreds of MB for nothing.
+          cache: false
+
+      - name: Build the image
+        run: make build-eks-node-mkosi-image

.github/workflows/perf-3node.yml

@@ -0,0 +1,415 @@
+name: Predastore 3-Node Performance
+
+on:
+  workflow_dispatch:
+    inputs:
+      perf_preset:
+        description: "Warp workload preset: smoke (30s) or compare (2m)"
+        required: false
+        default: compare
+        type: choice
+        options:
+          - smoke
+          - compare
+      cluster_ref:
+        description: "Git ref to build the cluster from, e.g. v1.18.0. Empty uses this branch."
+        required: false
+        default: ""
+        type: string
+
+# Shared with e2e.yml and e2e-nightly.yml: this job provisions on the same
+# hypervisors they do, so a run in flight there and here would compete for
+# disks and libvirt guests. Queued, not cancelled, same as those workflows.
+concurrency:
+  group: e2e-hypervisors
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+env:
+  GIT_BRANCH: ${{ github.ref_name }}
+  SPINIFEX_OTLP_ENDPOINT: ${{ vars.SPINIFEX_OTLP_ENDPOINT || 'http://192.168.1.13:8200' }}
+
+jobs:
+  perf_3node:
+    name: Predastore Throughput (3-node)
+    # ci-multi is a systemd runner on the LAN, not the ephemeral pool. A pool
+    # VM sits behind the geneve overlay at MTU 1408, which would put the
+    # runner's own network path inside the thing being measured.
+    runs-on: [self-hosted, ci-multi]
+    timeout-minutes: 90
+    env:
+      TOFU_LOG: /tmp/e2e-tofu-perf3node-${{ github.run_id }}.log
+      SPINIFEX_OTEL_ATTRS: ci.run_id=${{ github.run_id }},ci.workflow=${{ github.workflow }},ci.cell=perf-3node
+    steps:
+      - name: Reap Orphan Procs
+        run: |
+          set +e
+          UID_SELF=$(id -u)
+          WS="${GITHUB_WORKSPACE}"
+          reap() {
+            local sig="$1"
+            for pid in $(pgrep -u "$UID_SELF" -x tofu) $(pgrep -u "$UID_SELF" -x terraform); do
+              cwd=$(readlink "/proc/$pid/cwd" 2>/dev/null) || continue
+              case "$cwd" in
+                "$WS"|"$WS"/*) echo "reap $sig pid=$pid cwd=$cwd"; kill "-$sig" "$pid" 2>/dev/null ;;
+              esac
+            done
+          }
+          reap TERM
+          sleep 3
+          reap KILL
+          find "$WS" -name '.terraform.tfstate.lock.info' -delete 2>/dev/null
+          true
+
+      - name: Clean Workspace
+        run: |
+          awk -v w="$GITHUB_WORKSPACE" '$2 ~ "^"w {print $2}' /proc/mounts \
+            | sort -r | xargs -r -I{} sudo umount -l -R {} || true
+          sudo rm -rf --one-file-system "$GITHUB_WORKSPACE"/*
+
+      # ci-multi and ci-single resolve to the same physical host, so the
+      # nvme path cell-23 uses for its throughput run is already there.
+      # Pointing TMPDIR at it keeps warp's payloads off a small /tmp tmpfs.
+      - name: Configure work directories
+        run: |
+          E2E_ROOT=/mnt/nvme/e2e
+          mkdir -p "$E2E_ROOT/work" 2>/dev/null ||
+            { sudo mkdir -p "$E2E_ROOT/work" && sudo chown "$(id -u):$(id -g)" "$E2E_ROOT" "$E2E_ROOT/work"; }
+          echo "TMPDIR=$E2E_ROOT/work" >> "$GITHUB_ENV"
+          echo "PERF_RESULTS_ROOT=$E2E_ROOT/predastore-perf-3node-$GITHUB_RUN_ID" >> "$GITHUB_ENV"
+
+      - uses: actions/create-github-app-token@v3.3.0
+        id: app-token
+        with:
+          client-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+          repositories: mulga
+
+      - uses: actions/checkout@v7.0.1
+        with:
+          repository: mulgadc/mulga
+          token: ${{ steps.app-token.outputs.token }}
+          sparse-checkout: scripts/tofu-cluster
+          path: mulga
+
+      - uses: actions/checkout@v7.0.1
+        with:
+          path: spinifex
+
+      - uses: actions/setup-go@v7.0.0
+        with:
+          go-version-file: spinifex/go.mod
+          cache: false
+
+      - name: Re-enable Go toolchain auto-download
+        run: echo "GOTOOLCHAIN=auto" >> "$GITHUB_ENV"
+
+      # Same-named branch when one exists, dev otherwise. Matches how the
+      # e2e path picks siblings, so this measures the same predastore
+      # commit a cross-repo change would be built and tested against.
+      - name: Resolve sibling refs
+        id: siblings
+        env:
+          BRANCH: ${{ env.GIT_BRANCH }}
+        run: bash .github/resolve-sibling-refs.sh
+        working-directory: spinifex
+
+      - uses: actions/checkout@v7.0.1
+        id: predastore
+        with:
+          repository: mulgadc/predastore
+          ref: ${{ steps.siblings.outputs.predastore }}
+          path: predastore
+
+      # The cluster's ref is a knob and the harness's is not. Measuring an old
+      # release with a new harness is the only way its number can be set beside
+      # a current one; rebuilding both would change the ruler and the thing.
+      - name: Build Install Artifacts
+        working-directory: mulga/scripts/tofu-cluster
+        env:
+          CLUSTER_REF: ${{ inputs.cluster_ref }}
+        run: |
+          ./build-install-artifacts.sh "${CLUSTER_REF:-$GIT_BRANCH}" \
+            "${RUNNER_TEMP}/spinifex-distro.tar.gz" \
+            "${RUNNER_TEMP}/setup.sh" \
+            "${RUNNER_TEMP}/spinifex-tests.tar" \
+            --skip-e2e-build
+
+      # The libvirt provider dials the hypervisors by bare hostname. A pool VM
+      # sits inside a VPC and cannot resolve them; a LAN runner already can, so
+      # this is self-gating on the lookup rather than on the runner's labels.
+      - name: Map hypervisor names
+        working-directory: mulga/scripts/tofu-cluster
+        run: |
+          set -euo pipefail
+          if getent hosts banksia >/dev/null; then
+            echo "hypervisor names already resolve"
+          else
+            sudo tee -a /etc/hosts < network/hosts >/dev/null
+            echo "added $(grep -c '^[0-9]' network/hosts) entries to /etc/hosts"
+          fi
+          # Pinned rather than StrictHostKeyChecking=no: these hops reach the
+          # hypervisors themselves, so an unverified key is the one place in
+          # this job where accepting anything would matter.
+          if ssh-keygen -F banksia >/dev/null 2>&1; then
+            echo "hypervisor host keys already known"
+          else
+            install -d -m 700 ~/.ssh
+            cat network/known_hosts >> ~/.ssh/known_hosts
+            chmod 600 ~/.ssh/known_hosts
+            echo "pinned $(grep -c '^[a-z]' network/known_hosts) host keys"
+          fi
+
+      - name: Provision VMs
+        working-directory: mulga/scripts/tofu-cluster
+        run: |
+          set -euo pipefail
+          source "${GITHUB_WORKSPACE}/spinifex/.github/scripts/ci-fmt.sh"
+          export TF_VAR_git_branch="${GIT_BRANCH}"
+          quiet_run "tofu init"                "$TOFU_LOG" tofu init -input=false
+          quiet_run "tofu workspace select"    "$TOFU_LOG" tofu workspace select -or-create "${SPINIFEX_CI_ENV}"
+          quiet_run "tofu destroy (pre-clean)" "$TOFU_LOG" tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false || true
+          quiet_run "scrub-env (pre-clean)"    "$TOFU_LOG" ./scrub-env.sh "${SPINIFEX_CI_ENV}" || true
+          retry_run "tofu apply"               "$TOFU_LOG" tofu apply -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
+          ok "3-node cluster provisioned"
+
+      - name: Bootstrap via Binary Install
+        working-directory: mulga/scripts/tofu-cluster
+        run: |
+          SPX_EXTERNAL_POOL="${SPINIFEX_CI_POOL}" \
+          ./bootstrap-install.sh "${SPINIFEX_CI_ENV}" \
+            "${RUNNER_TEMP}/setup.sh" \
+            "${RUNNER_TEMP}/spinifex-distro.tar.gz" \
+            --test-tar "${RUNNER_TEMP}/spinifex-tests.tar"
+
+      - name: Resolve cluster SSH details
+        id: cluster
+        working-directory: mulga/scripts/tofu-cluster
+        run: |
+          INVENTORY=$(tofu output -json inventory)
+          NODE1_IP=$(echo "$INVENTORY" | jq -r '.nodes[0].wan_ip')
+          SSH_KEY=$(echo "$INVENTORY" | jq -r '.ssh_key_path')
+          SSH_KEY="${SSH_KEY/#\~/$HOME}"
+          SSH_USER=$(echo "$INVENTORY" | jq -r '.ssh_user')
+          REGION=$(echo "$INVENTORY" | jq -r '.region')
+          NODE_COUNT=$(echo "$INVENTORY" | jq '.nodes | length')
+          NODES_CSV=""
+          for i in $(seq 0 $((NODE_COUNT - 1))); do
+            ip=$(echo "$INVENTORY" | jq -r ".nodes[$i].wan_ip")
+            if [ -z "$NODES_CSV" ]; then NODES_CSV="$ip"; else NODES_CSV="$NODES_CSV,$ip"; fi
+          done
+          echo "node1_ip=${NODE1_IP}" >> "$GITHUB_OUTPUT"
+          echo "ssh_key=${SSH_KEY}" >> "$GITHUB_OUTPUT"
+          echo "ssh_user=${SSH_USER}" >> "$GITHUB_OUTPUT"
+          echo "region=${REGION}" >> "$GITHUB_OUTPUT"
+          echo "nodes_csv=${NODES_CSV}" >> "$GITHUB_OUTPUT"
+
+      # PERF_EXTERNAL_HOSTS wants host:port, and the gate listens on 8443 on
+      # every node. run-info.txt from this run is then comparable with the
+      # nightly's loopback one, since the harness itself never changes.
+      - name: Resolve PERF_EXTERNAL_HOSTS
+        id: perf_hosts
+        run: |
+          set -euo pipefail
+          IFS=',' read -ra NODE_LIST <<< "${{ steps.cluster.outputs.nodes_csv }}"
+          HOSTS=""
+          for ip in "${NODE_LIST[@]}"; do
+            [ -z "$ip" ] && continue
+            if [ -z "$HOSTS" ]; then HOSTS="$ip:8443"; else HOSTS="$HOSTS,$ip:8443"; fi
+          done
+          echo "hosts=${HOSTS}" >> "$GITHUB_OUTPUT"
+
+      # A slow bootstrap should fail here, legibly, rather than inside warp
+      # with a wall of connection-refused errors. Bounded at 5 minutes per
+      # gate so a genuinely dead node still fails the job in finite time.
+      - name: Wait for gates to answer on :8443
+        run: |
+          set -euo pipefail
+          IFS=',' read -ra GATES <<< "${{ steps.perf_hosts.outputs.hosts }}"
+          for gate in "${GATES[@]}"; do
+            echo "waiting for https://$gate"
+            up=0
+            for i in $(seq 1 60); do
+              if curl -k -sS --max-time 5 -o /dev/null "https://$gate/"; then
+                up=1
+                break
+              fi
+              sleep 5
+            done
+            [ "$up" -eq 1 ] || { echo "::error::gate $gate never answered HTTPS on :8443"; exit 1; }
+            echo "gate $gate is up"
+          done
+
+      # Warp reads whole objects, so no workload here touches a ranged read and
+      # the throughput figures stay healthy while ranged GETs are broken. This
+      # probe is the only thing in CI that looks at them.
+      - name: Ranged GET probe
+        env:
+          GATE: ${{ steps.cluster.outputs.node1_ip }}
+          SSH_KEY: ${{ steps.cluster.outputs.ssh_key }}
+          SSH_USER: ${{ steps.cluster.outputs.ssh_user }}
+          NODE1_IP: ${{ steps.cluster.outputs.node1_ip }}
+          CLUSTER_REGION: ${{ steps.cluster.outputs.region }}
+        run: |
+          set -euo pipefail
+          CREDS=$(ssh -i "${SSH_KEY}" -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+            "${SSH_USER}@${NODE1_IP}" 'cat ~/.aws/credentials')
+          AK=$(echo "$CREDS" | awk -F '= *' '/^aws_access_key_id/ {print $2; exit}')
+          SK=$(echo "$CREDS" | awk -F '= *' '/^aws_secret_access_key/ {print $2; exit}')
+          echo "::add-mask::$SK"
+          B="ranged-probe-${GITHUB_RUN_ID}"
+          AWSX=(--region "$CLUSTER_REGION" --endpoint-url "https://${GATE}:8443" --no-verify-ssl)
+          export AWS_ACCESS_KEY_ID="$AK" AWS_SECRET_ACCESS_KEY="$SK"
+          aws s3 mb "s3://$B" "${AWSX[@]}"
+          trap 'aws s3 rb "s3://$B" --force "${AWSX[@]}" >/dev/null 2>&1 || true' EXIT
+          # Two sizes: read amplification makes a boundary-crossing range cost
+          # the whole object, so the fault shows as time tracking object size.
+          for mb in 64 256; do
+            head -c $((mb*1024*1024)) /dev/urandom > "${TMPDIR}/probe-${mb}.bin"
+            aws s3 cp "${TMPDIR}/probe-${mb}.bin" "s3://$B/probe-${mb}.bin" --only-show-errors "${AWSX[@]}"
+            rm -f "${TMPDIR}/probe-${mb}.bin"
+          done
+          t() {
+            curl -sk --aws-sigv4 "aws:amz:${CLUSTER_REGION}:s3" -u "$AK:$SK" \
+              -H "Range: bytes=0-$1" -o /dev/null -w '%{time_total}' \
+              --url "https://${GATE}:8443/${B}/probe-${2}.bin"
+          }
+          # 4194304 is the last byte inside the first 4 MiB block; one more
+          # crosses into the second and leaves the single-shard fast path.
+          IN64=$(t 4194303 64);  OUT64=$(t 4194304 64)
+          IN256=$(t 4194303 256); OUT256=$(t 4194304 256)
+          printf '%-10s in-block=%ss  crossing=%ss\n' "64MiB" "$IN64" "$OUT64"
+          printf '%-10s in-block=%ss  crossing=%ss\n' "256MiB" "$IN256" "$OUT256"
+          # The 4x object-size ratio is the signal, and it is compared against
+          # the crossing reads alone so a slow runner cancels out of both sides.
+          awk -v a="$OUT64" -v b="$OUT256" 'BEGIN{
+            r = (a > 0) ? b/a : 0
+            printf "crossing-range cost ratio 256MiB/64MiB = %.2f (object size ratio is 4.00)\n", r
+            if (r > 2.0) {
+              print "::error::a boundary-crossing ranged GET scales with object size, so it is reading the whole object"
+              exit 1
+            }
+          }'
+          echo "ranged GET does not scale with object size"
+
+      # The benchmark works in $TMPDIR and predastore refuses writes below a 5%
+      # free-space watermark, so this asserts the same headroom cell-23 does.
+      # tmpfs is rejected outright: that would measure RAM, not the gates.
+      - name: Preflight
+        run: |
+          set -euo pipefail
+          mkdir -p "$TMPDIR"
+          fstype=$(df --output=fstype "$TMPDIR" | tail -1 | tr -d ' ')
+          case "$fstype" in
+            tmpfs|ramfs)
+              echo "::error::$TMPDIR is $fstype — a storage benchmark there measures RAM"
+              exit 1 ;;
+          esac
+          find "$TMPDIR" -maxdepth 1 -name 'predastore-e2e-performance.*' \
+               -type d -mtime +0 -exec rm -rf {} + 2>/dev/null || true
+          df -h "$TMPDIR"
+          avail_gb=$(df -BG --output=avail "$TMPDIR" | tail -1 | tr -dc '0-9')
+          pct_used=$(df --output=pcent "$TMPDIR" | tail -1 | tr -dc '0-9')
+          if [ "$pct_used" -ge 90 ] || [ "$avail_gb" -lt 20 ]; then
+            echo "::error::$TMPDIR ($fstype) is ${pct_used}% full with ${avail_gb} GiB free."
+            echo "::error::The benchmark needs headroom above predastore's 5% watermark."
+            exit 1
+          fi
+
+      - name: Install warp
+        working-directory: predastore
+        run: make warp-install
+
+      # PERF_EXTERNAL_HOSTS skips profile selection, port offsetting, and
+      # cluster start/stop, and measures these three gates directly. Same
+      # workloads and analysis as the nightly loopback run, so the numbers
+      # from the two are directly comparable.
+      #
+      # The cluster's credentials are read and used inside this one step, the
+      # way e2e-ddil.yml does it: a step-level env: block is echoed verbatim
+      # into the run log, and a shell variable is not.
+      - name: Run 3-node throughput benchmark
+        working-directory: predastore
+        env:
+          PERF_EXTERNAL_HOSTS: ${{ steps.perf_hosts.outputs.hosts }}
+          PERF_CONFIGS: spinifex-3node
+          PERF_PRESET: ${{ inputs.perf_preset || 'compare' }}
+          # What is deployed, not what the harness was checked out at. With a
+          # cluster_ref those differ, and run-info.txt records the cluster.
+          PERF_EXTERNAL_SHA: ${{ inputs.cluster_ref || steps.predastore.outputs.commit }}
+          SSH_KEY: ${{ steps.cluster.outputs.ssh_key }}
+          SSH_USER: ${{ steps.cluster.outputs.ssh_user }}
+          NODE1_IP: ${{ steps.cluster.outputs.node1_ip }}
+          CLUSTER_REGION: ${{ steps.cluster.outputs.region }}
+        run: |
+          set -euo pipefail
+          # spx admin init mints a random pair at bootstrap and writes it to
+          # node1's ~/.aws/credentials. The benchmark's built-in key is the one
+          # the loopback configs trust, which this cluster has never heard of.
+          CREDS=$(ssh -i "${SSH_KEY}" -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+            "${SSH_USER}@${NODE1_IP}" 'cat ~/.aws/credentials')
+          PERF_ACCESS_KEY=$(echo "$CREDS" | awk -F '= *' '/^aws_access_key_id/ {print $2; exit}')
+          PERF_SECRET_KEY=$(echo "$CREDS" | awk -F '= *' '/^aws_secret_access_key/ {print $2; exit}')
+          if [ -z "$PERF_ACCESS_KEY" ] || [ -z "$PERF_SECRET_KEY" ]; then
+            echo "::error::could not read spinifex AWS credentials from ${NODE1_IP}"
+            exit 1
+          fi
+          echo "::add-mask::$PERF_SECRET_KEY"
+          mkdir -p "$PERF_RESULTS_ROOT"
+          PERF_ACCESS_KEY="$PERF_ACCESS_KEY" \
+          PERF_SECRET_KEY="$PERF_SECRET_KEY" \
+          PERF_REGION="$CLUSTER_REGION" \
+            make e2e-performance 2>&1 | tee "$PERF_RESULTS_ROOT/e2e-performance.log"
+
+      # Report-only, matching cell-23: the baseline comparison and any
+      # regression gate are future work once run-to-run spread is known from
+      # real bare-metal runs.
+      - uses: actions/upload-artifact@v7.0.2
+        if: always()
+        with:
+          name: predastore-perf-3node-${{ github.run_id }}
+          path: ${{ env.PERF_RESULTS_ROOT }}
+          if-no-files-found: warn
+          retention-days: 90
+
+      - name: Clean up results
+        if: always()
+        run: rm -rf "${PERF_RESULTS_ROOT}"
+
+      - name: Teardown
+        if: always()
+        working-directory: mulga/scripts/tofu-cluster
+        run: |
+          set +e
+          source "${GITHUB_WORKSPACE}/spinifex/.github/scripts/ci-fmt.sh"
+          UID_SELF=$(id -u)
+          WS="${GITHUB_WORKSPACE}"
+          reap() {
+            local sig="$1"
+            for pid in $(pgrep -u "$UID_SELF" -x tofu) $(pgrep -u "$UID_SELF" -x terraform); do
+              cwd=$(readlink "/proc/$pid/cwd" 2>/dev/null) || continue
+              case "$cwd" in
+                "$WS"|"$WS"/*) kill "-$sig" "$pid" 2>/dev/null ;;
+              esac
+            done
+          }
+          reap TERM
+          sleep 2
+          reap KILL
+          find "$WS" -name '.terraform.tfstate.lock.info' -delete 2>/dev/null
+          quiet_run "tofu workspace select" "$TOFU_LOG" tofu workspace select -or-create "${SPINIFEX_CI_ENV}"
+          quiet_run "telemetry flush"       "$TOFU_LOG" timeout 120 ./flush-telemetry.sh "${SPINIFEX_CI_ENV}" || true
+          retry_run "tofu destroy"          "$TOFU_LOG" timeout 600 tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
+          quiet_run "scrub-env"             "$TOFU_LOG" ./scrub-env.sh "${SPINIFEX_CI_ENV}"
+          ok "teardown complete"
+
+      - name: Upload tofu log
+        if: always()
+        uses: actions/upload-artifact@v7.0.2
+        with:
+          name: tofu-log-perf3node-${{ github.run_id }}
+          path: ${{ env.TOFU_LOG }}
+          if-no-files-found: ignore
+          retention-days: 14

.github/workflows/publish-system-ami.yml

@@ -17,28 +17,12 @@ name: Publish System AMIs
 #   spx admin images import --name spinifex-rds-postgres
 #   spx admin images import --name spinifex-rds-mariadb
 #
-# Publishing overwrites the mirror artifact, so it is a deliberate action, not
-# something every push should trigger: it runs manually, or from release.yml
-# once a tag has passed its gates. The `variant` input scopes which images
-# build — the Ubuntu GPU legs are 16G and much slower (NVIDIA driver download +
-# DKMS build), so publishing only the CPU AMIs stays cheap.
+# Publishing overwrites the mirror artifact, so it runs only from release.yml
+# once a tag has passed its gates, with siblings at the tags go.mod requires.
+# The `variant` input scopes which images build — the Ubuntu GPU legs are 16G
+# and much slower (NVIDIA driver download + DKMS build).
 
 on:
-  workflow_dispatch:
-    inputs:
-      variant:
-        description: "Which images to build"
-        type: choice
-        default: all
-        options:
-          - all
-          - cpu
-          - gpu
-          - rds
-      dry_run:
-        description: "Build + convert only; skip the R2 upload"
-        type: boolean
-        default: false
   workflow_call:
     inputs:
       variant:
@@ -60,7 +44,7 @@ concurrency:
 jobs:
   matrix:
     name: Resolve image matrix
-    runs-on: [ self-hosted, ci-single ]
+    runs-on: [self-hosted, ci-single]
     outputs:
       images: ${{ steps.gen.outputs.images }}
     steps:
@@ -84,7 +68,7 @@ jobs:
   publish:
     name: Build + publish ${{ matrix.name }}
     needs: matrix
-    runs-on: [ self-hosted, ci-single ]
+    runs-on: [self-hosted, ci-single]
     strategy:
       fail-fast: false
       # ci-single is one runner and each GPU build needs ~16G of scratch disk;
@@ -94,46 +78,48 @@ jobs:
 
     steps:
       - name: Checkout Spinifex
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           path: spinifex
 
+      - name: Resolve sibling release tags from go.mod
+        id: siblings
+        run: bash spinifex/.github/resolve-release-sibling-refs.sh spinifex/go.mod
+
       - name: Checkout Viperblock
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/viperblock
-          ref: dev
+          ref: ${{ steps.siblings.outputs.viperblock }}
           path: viperblock
 
       - name: Checkout Predastore
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/predastore
-          ref: dev
+          ref: ${{ steps.siblings.outputs.predastore }}
           path: predastore
 
       - name: Checkout Northstar
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/northstar
-          ref: dev
+          ref: ${{ steps.siblings.outputs.northstar }}
           path: northstar
 
       - name: Checkout Bluebottle
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/bluebottle
-          ref: dev
+          ref: ${{ steps.siblings.outputs.bluebottle }}
           path: bluebottle
 
       - name: Setup Go
-        uses: actions/setup-go@v7
+        uses: actions/setup-go@v7.0.0
         with:
           go-version-file: "spinifex/go.mod"
           # Self-hosted runner: the Go module + build cache already persists on
-          # local disk between runs. setup-go's cache-save ("Post Setup Go")
-          # otherwise re-uploads hundreds of MB to the Actions cache backend,
-          # taking longer than the build itself.
+          # local disk between runs.
           cache: false
 
       - name: Setup Go Workspace
@@ -160,7 +146,6 @@ jobs:
       - name: Build + publish ${{ matrix.name }} to R2
         working-directory: spinifex
         env:
-          # Map the repo's R2 secrets onto the names publish-system-image.sh reads.
           AWS_ACCESS_KEY_ID: ${{ secrets.CF_R2_ACCESS_KEY_ID }}
           AWS_SECRET_ACCESS_KEY: ${{ secrets.CF_R2_SECRET_ACCESS_KEY }}
           R2_ENDPOINT: ${{ secrets.CF_R2_ENDPOINT_URL }}

.github/workflows/release.yml

@@ -5,48 +5,57 @@ on:
     tags: [ "v*" ]
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
   distro-amd64:
     runs-on: ubuntu-26.04
     steps:
       - name: Checkout Spinifex
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           path: spinifex
 
+      - name: Resolve sibling release tags from go.mod
+        id: siblings
+        run: bash spinifex/.github/resolve-release-sibling-refs.sh spinifex/go.mod
+
       - name: Checkout Predastore
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/predastore
+          ref: ${{ steps.siblings.outputs.predastore }}
           path: predastore
 
       - name: Checkout Viperblock
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/viperblock
+          ref: ${{ steps.siblings.outputs.viperblock }}
           path: viperblock
 
       - name: Checkout Northstar
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/northstar
+          ref: ${{ steps.siblings.outputs.northstar }}
           path: northstar
 
       - name: Checkout Bluebottle
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/bluebottle
+          ref: ${{ steps.siblings.outputs.bluebottle }}
           path: bluebottle
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@v4.4.1
 
       - name: Set up Go
-        uses: actions/setup-go@v7
+        uses: actions/setup-go@v7.0.0
         with:
-          go-version: "1.27.0"
+          go-version-file: spinifex/go.mod
+          cache: false
 
       - name: Build microVM artifacts (lb-agent + kernel + initramfs)
         run: cd spinifex && make build-microvm-image
@@ -57,7 +66,7 @@ jobs:
         run: cd spinifex && make distro-amd64 VERSION="$VERSION"
 
       - name: Upload amd64 Artifacts
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
         with:
           name: distro-amd64
           path: |
@@ -69,36 +78,44 @@ jobs:
     runs-on: ubuntu-26.04-arm
     steps:
       - name: Checkout Spinifex
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           path: spinifex
 
+      - name: Resolve sibling release tags from go.mod
+        id: siblings
+        run: bash spinifex/.github/resolve-release-sibling-refs.sh spinifex/go.mod
+
       - name: Checkout Predastore
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/predastore
+          ref: ${{ steps.siblings.outputs.predastore }}
           path: predastore
 
       - name: Checkout Viperblock
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/viperblock
+          ref: ${{ steps.siblings.outputs.viperblock }}
           path: viperblock
 
       - name: Checkout Northstar
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/northstar
+          ref: ${{ steps.siblings.outputs.northstar }}
           path: northstar
 
       - name: Checkout Bluebottle
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/bluebottle
+          ref: ${{ steps.siblings.outputs.bluebottle }}
           path: bluebottle
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@v4.4.1
 
       - name: Build arm64 Tarball
         env:
@@ -106,7 +123,7 @@ jobs:
         run: cd spinifex && make distro-arm64 VERSION="$VERSION"
 
       - name: Upload arm64 Artifacts
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
         with:
           name: distro-arm64
           path: |
@@ -116,21 +133,23 @@ jobs:
   release:
     needs: [ distro-amd64, distro-arm64 ]
     runs-on: ubuntu-26.04
+    permissions:
+      contents: write
     steps:
       - name: Download amd64 Artifacts
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@v8.0.2
         with:
           name: distro-amd64
           path: artifacts
 
       - name: Download arm64 Artifacts
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@v8.0.2
         with:
           name: distro-arm64
           path: artifacts
 
       - name: Create Draft GitHub Release
-        uses: softprops/action-gh-release@v3
+        uses: softprops/action-gh-release@v3.0.3
         with:
           draft: true
           files: |
@@ -140,7 +159,7 @@ jobs:
           generate_release_notes: true
 
       - name: Upload Tarball for Verify Job
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
         with:
           name: release-assets
           path: artifacts/
@@ -148,6 +167,13 @@ jobs:
   verify:
     needs: release
     runs-on: [ self-hosted, ci-single ]
+    # Shared with the e2e workflows: this job provisions on the same runner
+    # pools and the same hypervisors, so two in flight compete for their disks
+    # and their libvirt guests. Job-level, so the build jobs are not queued
+    # behind a nightly that has nothing to do with them.
+    concurrency:
+      group: e2e-hypervisors
+      cancel-in-progress: false
     timeout-minutes: 25
     env:
       TOFU_LOG: /tmp/release-verify-${{ github.run_id }}.log
@@ -160,22 +186,29 @@ jobs:
             | sort -r | xargs -r -I{} sudo umount -l -R {} || true
           sudo rm -rf --one-file-system "$GITHUB_WORKSPACE"/*
 
-      - uses: actions/create-github-app-token@v3
+      - uses: actions/create-github-app-token@v3.3.0
         id: app-token
         with:
           client-id: ${{ secrets.APP_ID }}
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
           repositories: mulga
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/mulga
           token: ${{ steps.app-token.outputs.token }}
           sparse-checkout: scripts/tofu-cluster
           path: mulga
 
+      # Only the shared shell helpers: this job builds nothing from source, but
+      # it drives the same libvirt provider the e2e cells retry around.
+      - uses: actions/checkout@v7.0.1
+        with:
+          sparse-checkout: .github/scripts
+          path: spinifex
+
       - name: Download Release Assets
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@v8.0.2
         with:
           name: release-assets
           path: release-assets
@@ -183,11 +216,12 @@ jobs:
       - name: Provision VM
         working-directory: mulga/scripts/tofu-cluster
         run: |
+          source "${GITHUB_WORKSPACE}/spinifex/.github/scripts/ci-fmt.sh"
           tofu init -input=false >> "$TOFU_LOG" 2>&1
           tofu workspace select -or-create "${SPINIFEX_CI_ENV}" >> "$TOFU_LOG" 2>&1
           tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false >> "$TOFU_LOG" 2>&1 || true
           ./scrub-env.sh "${SPINIFEX_CI_ENV}" >> "$TOFU_LOG" 2>&1 || true
-          tofu apply -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false >> "$TOFU_LOG" 2>&1
+          retry_run "tofu apply" "$TOFU_LOG" tofu apply -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
 
       - name: Bootstrap via Binary Install
         working-directory: mulga/scripts/tofu-cluster
@@ -200,8 +234,9 @@ jobs:
         if: always()
         working-directory: mulga/scripts/tofu-cluster
         run: |
+          source "${GITHUB_WORKSPACE}/spinifex/.github/scripts/ci-fmt.sh"
           tofu workspace select -or-create "${SPINIFEX_CI_ENV}" >> "$TOFU_LOG" 2>&1
-          tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false >> "$TOFU_LOG" 2>&1
+          retry_run "tofu destroy" "$TOFU_LOG" tofu destroy -var-file=envs/${SPINIFEX_CI_ENV}.tfvars -auto-approve -input=false
           ./scrub-env.sh "${SPINIFEX_CI_ENV}" >> "$TOFU_LOG" 2>&1 || true
 
   baremetal:
@@ -215,6 +250,8 @@ jobs:
   promote:
     needs: [ verify, baremetal ]
     runs-on: ubuntu-26.04
+    permissions:
+      contents: write
     env:
       TAG: ${{ github.ref_name }}
       REPO: ${{ github.repository }}
@@ -247,6 +284,8 @@ jobs:
     needs: [ verify, baremetal ]
     if: failure()
     runs-on: ubuntu-26.04
+    permissions:
+      contents: write
     env:
       TAG: ${{ github.ref_name }}
       REPO: ${{ github.repository }}
@@ -264,6 +303,8 @@ jobs:
   iso:
     needs: release
     runs-on: [ self-hosted, ci-single ]
+    permissions:
+      contents: write
     # ISO build (~60-90m) overlaps the parallel baremetal run (~120m); the
     # upload gate then waits for baremetal to finish, so the job must outlast it.
     timeout-minutes: 180
@@ -278,7 +319,7 @@ jobs:
           sudo umount -l "${ROOTFS}/proc" 2>/dev/null || true
           sudo rm -rf --one-file-system "$GITHUB_WORKSPACE"/*
 
-      - uses: actions/create-github-app-token@v3
+      - uses: actions/create-github-app-token@v3.3.0
         id: app-token
         with:
           client-id: ${{ secrets.APP_ID }}
@@ -286,37 +327,45 @@ jobs:
           repositories: mulga
 
       - name: Checkout Spinifex
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           path: spinifex
           ref: ${{ github.ref }}
 
+      - name: Resolve sibling release tags from go.mod
+        id: siblings
+        run: bash spinifex/.github/resolve-release-sibling-refs.sh spinifex/go.mod
+
       - name: Checkout Predastore
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/predastore
+          ref: ${{ steps.siblings.outputs.predastore }}
           path: predastore
 
       - name: Checkout Viperblock
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/viperblock
+          ref: ${{ steps.siblings.outputs.viperblock }}
           path: viperblock
 
       - name: Checkout Northstar
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/northstar
+          ref: ${{ steps.siblings.outputs.northstar }}
           path: northstar
 
       - name: Checkout Bluebottle
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/bluebottle
+          ref: ${{ steps.siblings.outputs.bluebottle }}
           path: bluebottle
 
       - name: Checkout Mulga iso-builder
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/mulga
           token: ${{ steps.app-token.outputs.token }}
@@ -327,7 +376,7 @@ jobs:
         run: sudo make -C mulga/scripts/iso-builder clean
 
       - name: Set up Go
-        uses: actions/setup-go@v7
+        uses: actions/setup-go@v7.0.0
         with:
           go-version-file: spinifex/go.mod
           cache: false

.github/workflows/segscan-oracle.yml

@@ -3,7 +3,7 @@
 #
 # tests/integration/segscan_oracle_test.go needs the mulga umbrella repo's
 # scripts/segscan checked out alongside spinifex (it is a separate Go module,
-# `package main`, and cannot be imported — see spinifex/testutil/segscanoracle).
+# `package main`, and cannot be imported — see internal/testkit/segscanoracle).
 # spinifex.yml's jobs check out only spinifex/viperblock/predastore and run on
 # every PR; adding a second-repo checkout there would make every spinifex PR
 # depend on mulga main being healthy and pay that checkout cost on every run,
@@ -25,7 +25,7 @@ jobs:
 
     steps:
       - name: Checkout Spinifex
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           path: spinifex
           fetch-depth: 2
@@ -38,34 +38,34 @@ jobs:
         working-directory: spinifex
 
       - name: Checkout Viperblock
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/viperblock
           ref: ${{ steps.siblings.outputs.viperblock }}
           path: viperblock
 
       - name: Checkout Predastore
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/predastore
           ref: ${{ steps.siblings.outputs.predastore }}
           path: predastore
 
       - name: Checkout Northstar
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/northstar
           ref: ${{ steps.siblings.outputs.northstar }}
           path: northstar
 
       - name: Checkout Bluebottle
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/bluebottle
           ref: ${{ steps.siblings.outputs.bluebottle }}
           path: bluebottle
 
-      - uses: actions/create-github-app-token@v3
+      - uses: actions/create-github-app-token@v3.3.0
         id: app-token
         with:
           client-id: ${{ secrets.APP_ID }}
@@ -73,7 +73,7 @@ jobs:
           repositories: mulga
 
       - name: Checkout Mulga (scripts/segscan only)
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/mulga
           token: ${{ steps.app-token.outputs.token }}
@@ -81,7 +81,7 @@ jobs:
           path: mulga
 
       - name: Setup Go
-        uses: actions/setup-go@v7
+        uses: actions/setup-go@v7.0.0
         with:
           cache-dependency-path: "spinifex/go.sum"
           go-version-file: "spinifex/go.mod"

.github/workflows/spinifex.yml

@@ -27,7 +27,7 @@ jobs:
 
     steps:
       - name: Checkout Spinifex
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           path: spinifex
           fetch-depth: 2
@@ -40,28 +40,28 @@ jobs:
         working-directory: spinifex
 
       - name: Checkout Viperblock
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/viperblock
           ref: ${{ steps.siblings.outputs.viperblock }}
           path: viperblock
 
       - name: Checkout Predastore
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/predastore
           ref: ${{ steps.siblings.outputs.predastore }}
           path: predastore
 
       - name: Checkout Northstar
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/northstar
           ref: ${{ steps.siblings.outputs.northstar }}
           path: northstar
 
       - name: Checkout Bluebottle
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/bluebottle
           ref: ${{ steps.siblings.outputs.bluebottle }}
@@ -71,7 +71,7 @@ jobs:
       # the last go.sum change and never refreshed it. Both caches are managed
       # below instead.
       - name: Setup Go
-        uses: actions/setup-go@v7
+        uses: actions/setup-go@v7.0.0
         with:
           go-version-file: "spinifex/go.mod"
           cache: false
@@ -80,7 +80,7 @@ jobs:
       # setup-go hashed spinifex/go.sum alone, which left the sibling modules'
       # dependencies out of the key and re-downloading on every run.
       - name: Cache Go modules
-        uses: actions/cache@v6
+        uses: actions/cache@v6.1.0
         with:
           path: ~/go/pkg/mod
           key: gomod-${{ hashFiles('spinifex/go.sum', 'viperblock/go.sum', 'predastore/go.sum', 'northstar/go.sum', 'bluebottle/go.sum') }}
@@ -89,8 +89,11 @@ jobs:
       # Build artifacts follow source, so the key rolls per run and falls back to
       # this job's newest entry. Keyed per job because -race, -covermode=atomic
       # and plain builds produce disjoint entries and would evict each other.
-      - name: Cache Go build
-        uses: actions/cache@v6
+      # Restore runs everywhere; the matching save is gated to dev and main, so
+      # a PR reads the base branch's entry without spending a minute uploading
+      # one only that PR would ever read.
+      - name: Restore Go build cache
+        uses: actions/cache/restore@v6.1.0
         with:
           path: ~/.cache/go-build
           key: gobuild-${{ github.job }}-${{ github.run_id }}
@@ -131,18 +134,135 @@ jobs:
       - name: Check Diff Coverage
         run: cd spinifex && scripts/diff-coverage.sh coverage.out --base HEAD~1
 
-  # In-process integration tier (gateway.SetupRoutes over embedded NATS
-  # JetStream). Its own job so it runs in parallel with the unit tiers rather
-  # than adding to their wall time, and it still blocks a PR — unlike e2e.yml's
-  # "Integration (front gate)" job, which is push-triggered against main/dev on
-  # a self-hosted runner and so never gates a PR before merge.
-  integration_tests:
-    name: Integration Tests
+      # Compiled output stays valid whatever the tests said, and skipping the
+      # save on a red run would leave the next one rebuilding it, so this is
+      # gated on the branch rather than on success.
+      # Go bumps an entry's mtime when a run uses it, so this run's working set
+      # survives and objects superseded by later commits do not. Runs after the
+      # work, so it costs this job nothing and only shrinks what the next reads.
+      - name: Trim Go build cache
+        if: ${{ !cancelled() && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main') }}
+        run: |
+          C="$(go env GOCACHE)"
+          before=$(du -sm "$C" | cut -f1)
+          find "$C" -type f -mmin +240 -delete
+          echo "trimmed ${before}MB -> $(du -sm "$C" | cut -f1)MB"
+
+      - name: Save Go build cache
+        if: ${{ !cancelled() && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main') }}
+        uses: actions/cache/save@v6.1.0
+        with:
+          path: ~/.cache/go-build
+          key: gobuild-${{ github.job }}-${{ github.run_id }}
+
+  race_detection:
+    name: Race Detection
     runs-on: ubuntu-26.04
 
     steps:
       - name: Checkout Spinifex
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
+        with:
+          path: spinifex
+
+      - name: Resolve sibling refs
+        id: siblings
+        env:
+          BRANCH: ${{ github.head_ref || github.ref_name }}
+        run: bash .github/resolve-sibling-refs.sh
+        working-directory: spinifex
+
+      - name: Checkout Viperblock
+        uses: actions/checkout@v7.0.1
+        with:
+          repository: mulgadc/viperblock
+          ref: ${{ steps.siblings.outputs.viperblock }}
+          path: viperblock
+
+      - name: Checkout Predastore
+        uses: actions/checkout@v7.0.1
+        with:
+          repository: mulgadc/predastore
+          ref: ${{ steps.siblings.outputs.predastore }}
+          path: predastore
+
+      - name: Checkout Northstar
+        uses: actions/checkout@v7.0.1
+        with:
+          repository: mulgadc/northstar
+          ref: ${{ steps.siblings.outputs.northstar }}
+          path: northstar
+
+      - name: Checkout Bluebottle
+        uses: actions/checkout@v7.0.1
+        with:
+          repository: mulgadc/bluebottle
+          ref: ${{ steps.siblings.outputs.bluebottle }}
+          path: bluebottle
+
+      # setup-go's own cache only writes on a key miss, so it froze a snapshot at
+      # the last go.sum change and never refreshed it. Both caches are managed
+      # below instead.
+      - name: Setup Go
+        uses: actions/setup-go@v7.0.0
+        with:
+          go-version-file: "spinifex/go.mod"
+          cache: false
+
+      # Module contents follow the five go.sum files, so a content key is exact.
+      # setup-go hashed spinifex/go.sum alone, which left the sibling modules'
+      # dependencies out of the key and re-downloading on every run.
+      - name: Cache Go modules
+        uses: actions/cache@v6.1.0
+        with:
+          path: ~/go/pkg/mod
+          key: gomod-${{ hashFiles('spinifex/go.sum', 'viperblock/go.sum', 'predastore/go.sum', 'northstar/go.sum', 'bluebottle/go.sum') }}
+          restore-keys: gomod-
+
+      # Build artifacts follow source, so the key rolls per run and falls back to
+      # this job's newest entry. Keyed per job because -race, -covermode=atomic
+      # and plain builds produce disjoint entries and would evict each other.
+      # Restore runs everywhere; the matching save is gated to dev and main, so
+      # a PR reads the base branch's entry without spending a minute uploading
+      # one only that PR would ever read.
+      - name: Restore Go build cache
+        uses: actions/cache/restore@v6.1.0
+        with:
+          path: ~/.cache/go-build
+          key: gobuild-${{ github.job }}-${{ github.run_id }}
+          restore-keys: gobuild-${{ github.job }}-
+
+      - name: Setup Go Workspace
+        run: go work init ./spinifex ./viperblock ./predastore ./northstar ./bluebottle
+
+      - name: Run Tests with Race Detector
+        run: make -C spinifex test-race GOTESTFLAGS=-count=1
+
+      # Go bumps an entry's mtime when a run uses it, so this run's working set
+      # survives and objects superseded by later commits do not. Runs after the
+      # work, so it costs this job nothing and only shrinks what the next reads.
+      - name: Trim Go build cache
+        if: ${{ !cancelled() && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main') }}
+        run: |
+          C="$(go env GOCACHE)"
+          before=$(du -sm "$C" | cut -f1)
+          find "$C" -type f -mmin +240 -delete
+          echo "trimmed ${before}MB -> $(du -sm "$C" | cut -f1)MB"
+
+      - name: Save Go build cache
+        if: ${{ !cancelled() && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main') }}
+        uses: actions/cache/save@v6.1.0
+        with:
+          path: ~/.cache/go-build
+          key: gobuild-${{ github.job }}-${{ github.run_id }}
+
+  lint_and_security:
+    name: Lint + Security + Integration
+    runs-on: ubuntu-26.04
+
+    steps:
+      - name: Checkout Spinifex
+        uses: actions/checkout@v7.0.1
         with:
           path: spinifex
           fetch-depth: 2
@@ -155,28 +275,28 @@ jobs:
         working-directory: spinifex
 
       - name: Checkout Viperblock
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/viperblock
           ref: ${{ steps.siblings.outputs.viperblock }}
           path: viperblock
 
       - name: Checkout Predastore
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/predastore
           ref: ${{ steps.siblings.outputs.predastore }}
           path: predastore
 
       - name: Checkout Northstar
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/northstar
           ref: ${{ steps.siblings.outputs.northstar }}
           path: northstar
 
       - name: Checkout Bluebottle
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
           repository: mulgadc/bluebottle
           ref: ${{ steps.siblings.outputs.bluebottle }}
@@ -186,7 +306,7 @@ jobs:
       # the last go.sum change and never refreshed it. Both caches are managed
       # below instead.
       - name: Setup Go
-        uses: actions/setup-go@v7
+        uses: actions/setup-go@v7.0.0
         with:
           go-version-file: "spinifex/go.mod"
           cache: false
@@ -195,7 +315,7 @@ jobs:
       # setup-go hashed spinifex/go.sum alone, which left the sibling modules'
       # dependencies out of the key and re-downloading on every run.
       - name: Cache Go modules
-        uses: actions/cache@v6
+        uses: actions/cache@v6.1.0
         with:
           path: ~/go/pkg/mod
           key: gomod-${{ hashFiles('spinifex/go.sum', 'viperblock/go.sum', 'predastore/go.sum', 'northstar/go.sum', 'bluebottle/go.sum') }}
@@ -204,168 +324,11 @@ jobs:
       # Build artifacts follow source, so the key rolls per run and falls back to
       # this job's newest entry. Keyed per job because -race, -covermode=atomic
       # and plain builds produce disjoint entries and would evict each other.
-      - name: Cache Go build
-        uses: actions/cache@v6
-        with:
-          path: ~/.cache/go-build
-          key: gobuild-${{ github.job }}-${{ github.run_id }}
-          restore-keys: gobuild-${{ github.job }}-
-
-      - name: Setup Go Workspace
-        run: go work init ./spinifex ./viperblock ./predastore ./northstar ./bluebottle
-
-      - name: Run Integration Tests
-        run: make -C spinifex test-integration
-
-  race_detection:
-    name: Race Detection
-    runs-on: ubuntu-26.04
-
-    steps:
-      - name: Checkout Spinifex
-        uses: actions/checkout@v7
-        with:
-          path: spinifex
-
-      - name: Resolve sibling refs
-        id: siblings
-        env:
-          BRANCH: ${{ github.head_ref || github.ref_name }}
-        run: bash .github/resolve-sibling-refs.sh
-        working-directory: spinifex
-
-      - name: Checkout Viperblock
-        uses: actions/checkout@v7
-        with:
-          repository: mulgadc/viperblock
-          ref: ${{ steps.siblings.outputs.viperblock }}
-          path: viperblock
-
-      - name: Checkout Predastore
-        uses: actions/checkout@v7
-        with:
-          repository: mulgadc/predastore
-          ref: ${{ steps.siblings.outputs.predastore }}
-          path: predastore
-
-      - name: Checkout Northstar
-        uses: actions/checkout@v7
-        with:
-          repository: mulgadc/northstar
-          ref: ${{ steps.siblings.outputs.northstar }}
-          path: northstar
-
-      - name: Checkout Bluebottle
-        uses: actions/checkout@v7
-        with:
-          repository: mulgadc/bluebottle
-          ref: ${{ steps.siblings.outputs.bluebottle }}
-          path: bluebottle
-
-      # setup-go's own cache only writes on a key miss, so it froze a snapshot at
-      # the last go.sum change and never refreshed it. Both caches are managed
-      # below instead.
-      - name: Setup Go
-        uses: actions/setup-go@v7
-        with:
-          go-version-file: "spinifex/go.mod"
-          cache: false
-
-      # Module contents follow the five go.sum files, so a content key is exact.
-      # setup-go hashed spinifex/go.sum alone, which left the sibling modules'
-      # dependencies out of the key and re-downloading on every run.
-      - name: Cache Go modules
-        uses: actions/cache@v6
-        with:
-          path: ~/go/pkg/mod
-          key: gomod-${{ hashFiles('spinifex/go.sum', 'viperblock/go.sum', 'predastore/go.sum', 'northstar/go.sum', 'bluebottle/go.sum') }}
-          restore-keys: gomod-
-
-      # Build artifacts follow source, so the key rolls per run and falls back to
-      # this job's newest entry. Keyed per job because -race, -covermode=atomic
-      # and plain builds produce disjoint entries and would evict each other.
-      - name: Cache Go build
-        uses: actions/cache@v6
-        with:
-          path: ~/.cache/go-build
-          key: gobuild-${{ github.job }}-${{ github.run_id }}
-          restore-keys: gobuild-${{ github.job }}-
-
-      - name: Setup Go Workspace
-        run: go work init ./spinifex ./viperblock ./predastore ./northstar ./bluebottle
-
-      - name: Run Tests with Race Detector
-        run: make -C spinifex test-race GOTESTFLAGS=-count=1
-
-  lint_and_security:
-    name: Lint and Security
-    runs-on: ubuntu-26.04
-
-    steps:
-      - name: Checkout Spinifex
-        uses: actions/checkout@v7
-        with:
-          path: spinifex
-
-      - name: Resolve sibling refs
-        id: siblings
-        env:
-          BRANCH: ${{ github.head_ref || github.ref_name }}
-        run: bash .github/resolve-sibling-refs.sh
-        working-directory: spinifex
-
-      - name: Checkout Viperblock
-        uses: actions/checkout@v7
-        with:
-          repository: mulgadc/viperblock
-          ref: ${{ steps.siblings.outputs.viperblock }}
-          path: viperblock
-
-      - name: Checkout Predastore
-        uses: actions/checkout@v7
-        with:
-          repository: mulgadc/predastore
-          ref: ${{ steps.siblings.outputs.predastore }}
-          path: predastore
-
-      - name: Checkout Northstar
-        uses: actions/checkout@v7
-        with:
-          repository: mulgadc/northstar
-          ref: ${{ steps.siblings.outputs.northstar }}
-          path: northstar
-
-      - name: Checkout Bluebottle
-        uses: actions/checkout@v7
-        with:
-          repository: mulgadc/bluebottle
-          ref: ${{ steps.siblings.outputs.bluebottle }}
-          path: bluebottle
-
-      # setup-go's own cache only writes on a key miss, so it froze a snapshot at
-      # the last go.sum change and never refreshed it. Both caches are managed
-      # below instead.
-      - name: Setup Go
-        uses: actions/setup-go@v7
-        with:
-          go-version-file: "spinifex/go.mod"
-          cache: false
-
-      # Module contents follow the five go.sum files, so a content key is exact.
-      # setup-go hashed spinifex/go.sum alone, which left the sibling modules'
-      # dependencies out of the key and re-downloading on every run.
-      - name: Cache Go modules
-        uses: actions/cache@v6
-        with:
-          path: ~/go/pkg/mod
-          key: gomod-${{ hashFiles('spinifex/go.sum', 'viperblock/go.sum', 'predastore/go.sum', 'northstar/go.sum', 'bluebottle/go.sum') }}
-          restore-keys: gomod-
-
-      # Build artifacts follow source, so the key rolls per run and falls back to
-      # this job's newest entry. Keyed per job because -race, -covermode=atomic
-      # and plain builds produce disjoint entries and would evict each other.
-      - name: Cache Go build
-        uses: actions/cache@v6
+      # Restore runs everywhere; the matching save is gated to dev and main, so
+      # a PR reads the base branch's entry without spending a minute uploading
+      # one only that PR would ever read.
+      - name: Restore Go build cache
+        uses: actions/cache/restore@v6.1.0
         with:
           path: ~/.cache/go-build
           key: gobuild-${{ github.job }}-${{ github.run_id }}
@@ -375,10 +338,32 @@ jobs:
         run: go work init ./spinifex ./viperblock ./predastore ./northstar ./bluebottle
 
       - name: Lint
-        uses: golangci/golangci-lint-action@v9
+        uses: golangci/golangci-lint-action@v9.3.0
         with:
-          version: v2.13.0
+          version: v2.14.0
           working-directory: spinifex
 
       - name: Govulncheck
         run: make -C spinifex govulncheck
+
+      - name: Run Integration Tests
+        if: ${{ !cancelled() }}
+        run: make -C spinifex test-integration
+
+      # Go bumps an entry's mtime when a run uses it, so this run's working set
+      # survives and objects superseded by later commits do not. Runs after the
+      # work, so it costs this job nothing and only shrinks what the next reads.
+      - name: Trim Go build cache
+        if: ${{ !cancelled() && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main') }}
+        run: |
+          C="$(go env GOCACHE)"
+          before=$(du -sm "$C" | cut -f1)
+          find "$C" -type f -mmin +240 -delete
+          echo "trimmed ${before}MB -> $(du -sm "$C" | cut -f1)MB"
+
+      - name: Save Go build cache
+        if: ${{ !cancelled() && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main') }}
+        uses: actions/cache/save@v6.1.0
+        with:
+          path: ~/.cache/go-build
+          key: gobuild-${{ github.job }}-${{ github.run_id }}

.github/workflows/ui.yml

@@ -6,14 +6,14 @@ on:
       - main
       - dev
     paths:
-      - spinifex/services/spinifexui/frontend/**
+      - spinifex/runtime/roles/spinifexui/frontend/**
       - .github/workflows/ui.yml
   pull_request:
     branches:
       - main
       - dev
     paths:
-      - spinifex/services/spinifexui/frontend/**
+      - spinifex/runtime/roles/spinifexui/frontend/**
       - .github/workflows/ui.yml
   workflow_dispatch:
 
@@ -26,25 +26,25 @@ jobs:
     runs-on: ubuntu-26.04
     defaults:
       run:
-        working-directory: spinifex/services/spinifexui/frontend
+        working-directory: spinifex/runtime/roles/spinifexui/frontend
 
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
         with:
-          sparse-checkout: spinifex/services/spinifexui/frontend
+          sparse-checkout: spinifex/runtime/roles/spinifexui/frontend
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v6
+        uses: pnpm/action-setup@v6.1.0
         with:
-          package_json_file: spinifex/services/spinifexui/frontend/package.json
+          package_json_file: spinifex/runtime/roles/spinifexui/frontend/package.json
 
       - name: Setup Node.js
-        uses: actions/setup-node@v7
+        uses: actions/setup-node@v7.1.0
         with:
           cache: "pnpm"
-          cache-dependency-path: spinifex/services/spinifexui/frontend/pnpm-lock.yaml
-          node-version-file: spinifex/services/spinifexui/frontend/.nvmrc
+          cache-dependency-path: spinifex/runtime/roles/spinifexui/frontend/pnpm-lock.yaml
+          node-version-file: spinifex/runtime/roles/spinifexui/frontend/.nvmrc
 
       - name: Install Dependencies
         run: pnpm install --frozen-lockfile
@@ -58,5 +58,14 @@ jobs:
       - name: Build Frontend
         run: pnpm build
 
-      - name: Check for generated route tree drift
-        run: git diff --exit-code -- src/routeTree.gen.ts
+      # spx embeds the committed dist/, so a bundle that differs from a clean
+      # build of this source would ship JavaScript CI never built. Porcelain
+      # rather than git diff, so added and deleted chunks count too.
+      - name: Check for generated file drift
+        run: |
+          drift=$(git status --porcelain -- src/routeTree.gen.ts src/lib/cn-tables.gen.ts dist)
+          if [ -n "$drift" ]; then
+            echo "::error::Generated files differ from a clean build. Run pnpm build and commit the result."
+            echo "$drift"
+            exit 1
+          fi

.gitignore

@@ -19,7 +19,7 @@ bin/
 dist/
 build/microvm/vmlinuz
 build/microvm/initramfs.cpio.gz
-!spinifex/services/spinifexui/frontend/dist/
+!spinifex/runtime/roles/spinifexui/frontend/dist/
 tmp/
 *.test
 *.out
@@ -41,3 +41,4 @@ Thumbs.db
 
 # Test reports
 *-report.txt
+/rds-agent

.golangci.yml

@@ -1,5 +1,8 @@
 version: "2"
 
+run:
+  allow-serial-runners: true
+
 issues:
   max-same-issues: 10
 
@@ -56,7 +59,6 @@ linters:
     - unconvert # removes unnecessary type conversions
     - usestdlibvars # detects hardcoded values that should use stdlib constants
     - usetesting # catches os.TempDir() etc. in tests — should use t.TempDir()
-    - wastedassign # finds assignments to variables that are never subsequently read
     - whitespace # detects leading and trailing whitespace in functions
 
   settings:
@@ -69,17 +71,18 @@ linters:
             - pkg: math/rand$
               desc: Use math/rand/v2 instead, see https://go.dev/blog/randv2
 
-        # The EC2 control plane reaches block storage through ebsprovider, not
+        # The control plane reaches block storage through the EBS provider, not
         # by importing the engine. viperblock.New starts a chunk uploader, so
         # every construction is a writer against a volume viperblockd serves.
-        # Nothing under handlers/ may import viperblock, in any form, tests
+        # No domain or legacy handler may import viperblock, in any form, tests
         # included. A types-only import counts: one became an engine import.
         ec2-control-plane:
           files:
+            - '**/spinifex/domains/**'
             - '**/spinifex/handlers/**'
           deny:
             - pkg: github.com/mulgadc/viperblock
-              desc: Use the ebsprovider.EBSProvider interface; the control plane must not construct or name viperblock types.
+              desc: Use the providers/ebs EBSProvider interface; the control plane must not construct or name viperblock types.
 
     embeddedstructfieldcheck:
       forbid-mutex: true
@@ -107,6 +110,7 @@ linters:
         - G116 # bidi chars — bidichk is more thorough
         - G117 # use of net/http serve functions (we handle TLS separately)
         - G703 # path traversal taint analysis — false positives on config file loading
+        - G704 # SSRF taint analysis — false positives on resolver-derived endpoint URLs
         - G705 # XSS taint analysis — false positives on internal error responses
 
     govet:
@@ -142,15 +146,11 @@ linters:
     staticcheck:
       checks:
         - all
-        - -ST1000 # package comment
         - -ST1003 # naming conventions (Id→ID etc.) — too noisy to retrofit
         - -ST1012 # error var naming — errname covers this + error type suffixes
         - -ST1013 # HTTP status constants — usestdlibvars is broader
         - -ST1016 # receiver name consistency (too noisy to retrofit)
-        - -ST1020 # godoc on exported types — not enforcing yet
-        - -ST1021 # godoc on exported type groups — not enforcing yet
-        - -ST1022 # godoc on exported vars/consts — not enforcing yet
-        - -SA4006 # value overwritten — ineffassign + wastedassign cover this better
+        - -SA4006 # value overwritten — ineffassign catches strictly more of these
         - -SA9005 # marshaling structs with no exported fields — intended {} for empty API-response types
 
     testifylint:

CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# How to Contribute
+
+We welcome contributions to Spinifex!
+
+Report security vulnerabilities privately through [SECURITY.md](SECURITY.md), not as a public issue.
+
+**AWS parity is the design rule.** When Spinifex's behaviour is in question, the answer is what AWS does. If you believe Spinifex diverges from AWS, state what AWS does and show it with a test or a reproduction against a running cluster.
+
+## Understanding the Codebase
+
+Every AWS call enters through a SigV4-authenticated gateway, is published to NATS, and is answered by the daemon that claims it. Start with these:
+
+| Doc | Covers |
+|---|---|
+| [`docs/DESIGN.md`](docs/DESIGN.md) | Architecture, request flow, daemons, storage integration, file layout. |
+| [`docs/COMMANDS.md`](docs/COMMANDS.md) | The `spx admin` CLI and the systemd units it manages. |
+| [`docs/coverage/`](docs/coverage/README.md) | Which AWS API operations each service implements. |
+| [`scripts/README.md`](scripts/README.md) | Install, dev-environment, and image-build scripts. |
+| [`docs/PACKAGE_BOUNDARY_MIGRATION.md`](docs/PACKAGE_BOUNDARY_MIGRATION.md) | ADR-0001 implementation inventory and incremental source moves. |
+
+User-facing docs are published at [docs.mulgadc.com](https://docs.mulgadc.com).
+
+## Development Setup
+
+These steps build Spinifex from source and run it as a single-node cluster, following the [Source Install](https://docs.mulgadc.com/docs/install-source) guide.
+
+### Prerequisites
+
+- **Ubuntu 26.04** or **Debian 13**, on x86_64 or aarch64
+- A host with hardware virtualisation (KVM) and `sudo` access
+- The host's WAN interface enslaved to a Linux bridge named `br-wan`, with the host IP, default route and DHCP on the bridge rather than the bare NIC (see [VPC Networking → Bridge Setup](https://docs.mulgadc.com/docs/vpc-networking#bridge-setup-physical-network-wiring))
+
+Check the bridge before continuing:
+
+```bash
+ip -br link show br-wan   # bridge exists and is UP
+ip route                  # default route's dev is br-wan
+```
+
+### Install and Run
+
+```bash
+mkdir -p ~/Development/mulga && cd ~/Development/mulga
+git clone https://github.com/mulgadc/spinifex.git
+sudo make -C spinifex quickinstall        # system packages, Go 1.27, AWS CLI v2
+export PATH=$PATH:/usr/local/go/bin
+
+cd spinifex
+./scripts/clone-deps.sh                   # sibling repos: viperblock, predastore, northstar, bluebottle
+./scripts/dev-install.sh                  # build, install, init a one-node cluster, start services
+
+AWS_PROFILE=spinifex aws ec2 describe-instance-types
+```
+
+A list of instance types means the cluster is up.
+
+`make preflight` also needs `shellcheck` and `golangci-lint`
+
+```bash
+sudo apt-get install -y shellcheck
+curl -sSfL https://golangci-lint.run/install.sh | sh -s -- -b "$(go env GOPATH)/bin" v2.14.0
+```
+
+The web console additionally needs Node.js 24 and `pnpm`.
+
+## Development Workflow
+
+| Command | Use it to |
+|---|---|
+| `make deploy` | Rebuild, install `spx`, and restart `spinifex.target` after a code change. |
+| `make reinstall` | Re-run `dev-install.sh` after changing systemd units, helper scripts, or logrotate config. |
+| `./scripts/reset-dev-env.sh` | Wipe all cluster state and reinstall from scratch, keeping your network topology. |
+| `make test` | Run unit tests (`make test-race` for the race detector). |
+| `make test-integration` | Run the real gateway router against embedded NATS JetStream. |
+| `make preflight` | Run the pre-commit gate: lint, `govulncheck`, coverage, and manifest and script checks. Must pass. |
+
+Follow the services with `journalctl -u 'spinifex-*' -f`.
+
+The web console lives in `spinifex/runtime/roles/spinifexui/frontend/` (`pnpm install`, `pnpm dev`, `pnpm lint`, `pnpm test`). `spx` embeds its checked-in `dist/`, so run `make build-ui` and commit the rebuilt `dist/` with your change.
+
+## Creating a Pull Request
+
+1. Fork [mulgadc/spinifex](https://github.com/mulgadc/spinifex) and clone your fork into the same parent directory as the sibling repositories, branching off `dev`:
+
+   ```bash
+   cd ~/Development/mulga
+   git clone git@github.com:YOUR_USERNAME/spinifex.git && cd spinifex
+   git remote add upstream git@github.com:mulgadc/spinifex.git
+   git fetch upstream && git checkout -b feat/my-feature upstream/dev
+   ```
+
+2. Make your change, then verify it:
+   - `make preflight` passes.
+   - `go mod tidy` leaves only intended changes in `go.mod` and `go.sum`, with none of the `clone-deps.sh` `replace` lines.
+   - Runtime changes are exercised on your dev cluster with `make deploy`.
+
+3. Commit using [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:`), push, and open a pull request against `dev`, filling in the template.

Makefile

@@ -54,12 +54,12 @@ build: go_build build-installer build-lb-agent generate-aws-model-coverage
 # Build spinifex-ui frontend (requires pnpm)
 build-ui:
 	@echo -e "\n....Building spinifex-ui frontend...."
-	cd spinifex/services/spinifexui/frontend && pnpm build
+	cd spinifex/runtime/roles/spinifexui/frontend && pnpm build
 
 # GO commands
-VERSION ?= $(shell git describe --tags --always --dirty)
+VERSION ?= $(shell git describe --tags --always --dirty --exclude '*-dev')
 COMMIT  ?= $(shell git rev-parse --short HEAD)
-LDFLAGS := -s -w -X github.com/mulgadc/spinifex/cmd/spinifex/cmd.Version=$(VERSION) -X github.com/mulgadc/spinifex/cmd/spinifex/cmd.Commit=$(COMMIT)
+LDFLAGS := -s -w -X github.com/mulgadc/spinifex/spinifex/operator/cli.Version=$(VERSION) -X github.com/mulgadc/spinifex/spinifex/operator/cli.Commit=$(COMMIT)
 
 go_build:
 	@echo -e "\n....Building $(GO_PROJECT_NAME)"
@@ -79,7 +79,7 @@ build-ecs-agent: ## Build the ecs-agent (ships in the ECS-AMI guest; not in host
 
 build-loadgen: ## Build spx-loadgen (drives the stress harness's measured load; not shipped to nodes)
 	@echo -e "\n....Building spx-loadgen"
-	GOFIPS140=v1.0.0 go build -ldflags "-s -w" -o ./bin/spx-loadgen ./cmd/spx-loadgen
+	go build -ldflags "-s -w" -o ./bin/spx-loadgen ./cmd/spx-loadgen
 
 build-system-image: ## Build a system image from manifest (use IMAGE=lb or IMAGE=eks-node)
 ifndef IMAGE
@@ -103,6 +103,12 @@ import-eks-node-image: ## Build + register the eks-node AMI (requires a running
 publish-eks-node-image: ## Build + publish the eks-node AMI to Cloudflare R2 (needs R2_ENDPOINT + AWS_* env)
 	./scripts/publish-system-image.sh scripts/images/eks-node/manifest.conf --build
 
+# The Ubuntu/systemd EKS image, as opposed to build-eks-node-image's Alpine one.
+# Composition lives in mkosi-build.sh's image_profiles table, so the image name
+# is the whole interface here.
+build-eks-node-mkosi-image: ## Build the Ubuntu mkosi EKS node image (server+agent; role at first boot)
+	./scripts/mkosi-build.sh --image spinifex-eks-node
+
 build-ecs-node-image: ## Build the spinifex-ecs-node AMI (Alpine + containerd + ecs-agent; IMPORT=1 to register)
 	$(MAKE) build-system-image IMAGE=ecs-agent
 
@@ -143,55 +149,78 @@ install-microvm: $(MICROVM_ARTIFACTS) ## Install microVM artifacts to /usr/share
 
 # the pre-commit gate: manifest checks, lint, vuln, and the unit and e2e-harness tiers.
 # integration and race tests skipped to keep quick, they run in CI.
+#
+# -j2 overlaps the only two heavy gates, lint and test-cover: alone each leaves
+# most of the machine idle, so pairing them cuts a cold run by about a quarter.
+# -Otarget keeps each gate's output in one block instead of interleaving them.
+# manifest-check manifest-lint test-package-check removed, can add back later
 preflight:
-	@$(MAKE) --no-print-directory QUIET=1 manifest-check manifest-lint lint govulncheck test-cover diff-coverage test-package-check test-harness test-build-scripts
+	@$(MAKE) --no-print-directory -j2 -Otarget QUIET=1 lint govulncheck test-cover diff-coverage test-harness test-build-scripts manifest-check manifest-lint
 	@echo -e "\n ✅ Preflight passed — safe to commit."
 
 # Shell suites + shellcheck for build/scripts/, the systemd-unit helpers that
 # ship on every node (unlike scripts/images/, kept in preflight: a wrong
 # restart decision here is an outage, not asset churn).
+#
+# NODE_SCRIPTS are the four that setup.sh installs into
+# /usr/local/share/spinifex on every node. They are covered here for the same
+# reason: between them they install the software, wire OVN, erase the state and
+# remove the install, so a shellcheck warning in one is an outage or a wrong
+# deletion, not a style note.
+NODE_SCRIPTS := scripts/setup.sh scripts/setup-ovn.sh scripts/install-node.sh scripts/smoke-test.sh scripts/node-reset.sh scripts/uninstall-spx.sh
+
 test-build-scripts:
 	@echo -e "\n....Running build/scripts/**/*_test.sh...."
 	@for t in $$(find build/scripts -name '*_test.sh' | sort); do \
 		echo "-- $$t"; \
 		sh "$$t" || exit 1; \
 	done
-	@echo -e "\n....Running shellcheck over build/scripts/**/*.sh...."
-	shellcheck -S warning $$(find build/scripts -name '*.sh' | sort)
+	@echo -e "\n....Running scripts/*_test.sh...."
+	@for t in $$(find scripts -maxdepth 1 -name '*_test.sh' | sort); do \
+		echo "-- $$t"; \
+		sh "$$t" || exit 1; \
+	done
+	@echo -e "\n....Running shellcheck over build/scripts/**/*.sh + the node scripts...."
+	shellcheck -S warning $$(find build/scripts -name '*.sh' | sort) $(NODE_SCRIPTS)
 	@echo "  test-build-scripts ok"
 
 # E2E harness unit tests. Build-tagged `e2e` so they're skipped by the
 # default `go test ./spinifex/...`. Runs with mocked AWS clients — no
 # infrastructure required, safe to run in CI without a cluster.
+#
+# diskperf/ is here for the same reason: its baseline comparison and probe
+# accounting decide whether the disk-performance gate passes, and that
+# arithmetic has to be covered off-cluster or the gate is trusted untested.
 test-harness:
 	@echo -e "\n....Running e2e harness unit tests...."
-	$(_Q)LOG_IGNORE=1 go test -tags=e2e -timeout 60s ./tests/e2e/harness/... $(_RACEQ)
+	$(_Q)LOG_IGNORE=1 go test -tags=e2e -timeout 60s ./tests/e2e/harness/... ./tests/e2e/diskperf/... $(_RACEQ)
 
 # In-process integration tier: the real gateway router against embedded NATS
 # JetStream, with only the daemon-side NATS subjects stubbed.
 AWS_MODEL_CONFORMANCE_REPORT ?= $(CURDIR)/.cache/aws-model-conformance-report.txt
 AWS_MODEL_CONFORMANCE_MODE ?= fail
-AWS_MODEL_OPERATION_COVERAGE_REPORT ?= $(CURDIR)/docs/aws-model-operation-coverage.md
+AWS_MODEL_OPERATION_COVERAGE_DIR ?= $(CURDIR)/docs/coverage
 # -count=1 is load-bearing: the conformance report is written by the test binary,
 # so a cached pass skips the run, leaves no report, and the cat below fails the
 # target. It also keeps the conformance gate honest — a cached result would mean
-# the check never ran against this commit.
+# the check never ran against this commit. The generated request sweep adds
+# about 15s, most of it EC2 fan-outs waiting out their window for instances
+# no daemon-lite owns.
 test-integration:
 	@echo -e "\n....Running in-process integration tests...."
-	$(_Q)LOG_IGNORE=1 AWS_MODEL_CONFORMANCE_MODE=$(AWS_MODEL_CONFORMANCE_MODE) AWS_MODEL_CONFORMANCE_REPORT=$(AWS_MODEL_CONFORMANCE_REPORT) go test -count=1 -tags=integration -timeout 60s ./tests/integration/... $(_RACEQ)
+	$(_Q)LOG_IGNORE=1 AWS_MODEL_CONFORMANCE_MODE=$(AWS_MODEL_CONFORMANCE_MODE) AWS_MODEL_CONFORMANCE_REPORT=$(AWS_MODEL_CONFORMANCE_REPORT) go test -count=1 -tags=integration -timeout 120s ./tests/integration/... $(_RACEQ)
 	@cat $(AWS_MODEL_CONFORMANCE_REPORT)
 	@$(MAKE) --no-print-directory generate-aws-model-coverage
-	@echo "AWS operation coverage: $(AWS_MODEL_OPERATION_COVERAGE_REPORT)"
+	@echo "AWS operation coverage: $(AWS_MODEL_OPERATION_COVERAGE_DIR)"
 
 generate-aws-model-coverage:
-	@mkdir -p $(dir $(AWS_MODEL_OPERATION_COVERAGE_REPORT))
-	@go run ./cmd/aws-model-coverage > $(AWS_MODEL_OPERATION_COVERAGE_REPORT)
+	@go run ./cmd/aws-model-coverage -out $(AWS_MODEL_OPERATION_COVERAGE_DIR) -json $(AWS_MODEL_OPERATION_COVERAGE_DIR)/coverage.json
 
 aws-model-coverage: generate-aws-model-coverage
-	@cat $(AWS_MODEL_OPERATION_COVERAGE_REPORT)
+	@go run ./cmd/aws-model-coverage
 
 # Segscan storage oracle: needs the mulga umbrella repo's scripts/segscan
-# checked out alongside spinifex (see spinifex/testutil/segscanoracle), which
+# checked out alongside spinifex (see internal/testkit/segscanoracle), which
 # is not the default local or CI layout, so this is a separate target from
 # test-integration rather than folded into it. Skips itself when segscan's
 # source isn't found.
@@ -219,7 +248,7 @@ manifest-lint-update:
 # Run unit tests
 test:
 	@echo -e "\n....Running tests for $(GO_PROJECT_NAME)...."
-	LOG_IGNORE=1 go test -timeout 180s ./spinifex/... ./cmd/... ./internal/...
+	LOG_IGNORE=1 go test -timeout 180s ./spinifex/... ./cmd/... ./internal/... ./contracts/... ./architecture/...
 
 # Empty locally, where reusing a cached result between runs is the point.
 # CI passes -count=1 so a green run means the suite executed against that commit
@@ -230,13 +259,13 @@ GOTESTFLAGS ?=
 COVERPROFILE ?= coverage.out
 test-cover:
 	@echo -e "\n....Running tests with coverage for $(GO_PROJECT_NAME)...."
-	$(_Q)LOG_IGNORE=1 go test $(GOTESTFLAGS) -timeout 180s -coverprofile=$(COVERPROFILE) -covermode=atomic ./spinifex/... ./cmd/... ./internal/... $(_COVQ)
+	$(_Q)LOG_IGNORE=1 go test $(GOTESTFLAGS) -timeout 180s -coverprofile=$(COVERPROFILE) -covermode=atomic ./spinifex/... ./cmd/... ./internal/... ./contracts/... ./architecture/... $(_COVQ)
 	@scripts/check-coverage.sh $(COVERPROFILE) $(QUIET)
 
 # Run unit tests with race detector
 test-race:
 	@echo -e "\n....Running tests with race detector for $(GO_PROJECT_NAME)...."
-	$(_Q)LOG_IGNORE=1 go test $(GOTESTFLAGS) -race -timeout 300s ./spinifex/... ./cmd/... ./internal/... $(_RACEQ)
+	$(_Q)LOG_IGNORE=1 go test $(GOTESTFLAGS) -race -timeout 300s ./spinifex/... ./cmd/... ./internal/... ./contracts/... ./architecture/... $(_RACEQ)
 
 # Unit tests for in-repo GitHub Actions (e.g. .github/actions/e2e-analyze).
 # Kept out of `test-cover` so coverage % isn't diluted by CI-only tooling.
@@ -289,6 +318,17 @@ bench:
 	@echo -e "\n....Running benchmarks for $(GO_PROJECT_NAME)...."
 	LOG_IGNORE=1 go test -benchmem -run=. -bench=. ./...
 
+# Fuzz every Fuzz* target for FUZZTIME each; -fuzz takes one target per run.
+# Plain `go test` already replays the seeds and testdata/fuzz on preflight.
+FUZZTIME ?= 30s
+fuzz:
+	@set -e; grep -rlE '^func Fuzz\w+\(' --include='*_test.go' spinifex cmd internal | while read -r file; do \
+		for name in $$(grep -oE '^func Fuzz\w+' "$$file" | cut -d' ' -f2); do \
+			echo -e "\n....Fuzzing $$name ($$(dirname $$file)) for $(FUZZTIME)...."; \
+			LOG_IGNORE=1 go test -run='^$$' -fuzz="^$$name$$" -fuzztime=$(FUZZTIME) ./$$(dirname $$file); \
+		done; \
+	done
+
 # Fast iteration: build + install binary + restart all services.
 # Microvm artifacts are reinstalled when they already exist on disk — the rule's
 # input timestamps drive a rebuild only if anything actually changed. On a fresh
@@ -325,7 +365,7 @@ reinstall:
 
 clean:
 	rm -f ./bin/$(GO_PROJECT_NAME)
-	rm -rf spinifex/services/spinifexui/frontend/dist
+	rm -rf spinifex/runtime/roles/spinifexui/frontend/dist
 
 install-system:
 	@echo -e "\n....Installing system dependencies for $(ARCH)...."
@@ -339,9 +379,9 @@ install-system:
 		ovn-central ovn-host openvswitch-switch dhcpcd-base
 
 install-go:
-	@echo -e "\n....Installing Go 1.27.0 for $(ARCH) ($(GO_ARCH))...."
+	@echo -e "\n....Installing Go 1.27.3 for $(ARCH) ($(GO_ARCH))...."
 	@if [ ! -d "/usr/local/go" ]; then \
-		curl -L https://go.dev/dl/go1.27.0.linux-$(GO_ARCH).tar.gz | tar -C /usr/local -xz; \
+		curl -L https://go.dev/dl/go1.27.3.linux-$(GO_ARCH).tar.gz | tar -C /usr/local -xz; \
 	else \
 		echo "Go already installed in /usr/local/go"; \
 	fi
@@ -424,7 +464,7 @@ distro-arm64:
 distro-clean:
 	rm -rf dist/
 
-.PHONY: test-package-check build build-ui build-installer build-lb-agent build-ecs-agent build-system-image build-eks-node-image import-eks-node-image publish-eks-node-image build-ecs-node-image import-ecs-node-image build-rds-postgres-image import-rds-postgres-image build-rds-mariadb-image import-rds-mariadb-image build-microvm-image install-microvm go_build preflight test test-cover test-race diff-coverage bench test-actions test-images test-build-scripts test-harness test-integration generate-aws-model-coverage aws-model-coverage test-segscan-oracle manifest-check manifest-lint manifest-lint-update \
+.PHONY: test-package-check build build-ui build-installer build-lb-agent build-ecs-agent build-system-image build-eks-node-image import-eks-node-image publish-eks-node-image build-ecs-node-image import-ecs-node-image build-rds-postgres-image import-rds-postgres-image build-rds-mariadb-image import-rds-mariadb-image build-microvm-image install-microvm go_build preflight test test-cover test-race diff-coverage bench fuzz test-actions test-images test-build-scripts test-harness test-integration generate-aws-model-coverage aws-model-coverage test-segscan-oracle manifest-check manifest-lint manifest-lint-update \
 	deploy reinstall clean \
 	install-system install-go install-aws quickinstall \
 	lint fix govulncheck nilaway \

README.md

@@ -4,222 +4,136 @@
 
 <p align="center">
   <a href="https://go.dev"><img src="https://img.shields.io/badge/Go-1.27+-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go"></a>
+  <a href="https://pkg.go.dev/github.com/mulgadc/spinifex"><img src="https://img.shields.io/badge/pkg.go.dev-Reference-007D9C?style=flat-square&logo=go&logoColor=white" alt="Go Reference"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-3fb950?style=flat-square" alt="License"></a>
-  <a href="https://mulgadc.com"><img src="https://img.shields.io/badge/home-mulga-orange?style=flat-square&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9IiNmZmYiIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTE2LjcxOCA4Ljg5MWMtMS4yODUgMS4zNy0zLjE3OCAyLjMxNy00LjY5NSAzLjQ0LS44NTQuNjMtMy4wODkgMi4yNy0xLjYxIDMuMzQ0IDEuNzg4IDEuMjk4IDYuMjQzLjE2NCA3Ljc4NS0xLjI2Ljg0LS43NzUuODE0LTEuODIyLS4zMjgtMi4yNTktMS4yMzUtLjQ3Mi0yLjY2LS4xMTEtMy45MTMuMDg3LS4wNDIuMDA3LS4xMzEuMDU1LS4xMjMtLjAyLjUyMy0uMzM2Ljk5My0uNzUgMS41MDMtMS4xMDIuNDkyLS4zNCAxLjA5Ny0uODI3IDEuNy0uODM4IDEuODcxLS4wMzQgMy43OTkuODkgNC4yODcgMi44MTUuODExIDMuMjAzLTMuMDA2IDUuNzE1LTUuNzg0IDUuOTQybDEuNjE0LS43NDdjLjYwNS0uMzYgMS4yMTctLjczNCAxLjc1Mi0xLjE5Ni4xMzMtLjExNS4yMy0uMjYzLjM0Mi0uMzczLjAyNy0uMDI2LjMwMi0uMTQ0LjE0NC0uMTUtMS40NDEuOTQ1LTMuMTI3IDEuNTcyLTQuODEzIDEuOTMyLS41OC4xMjMtMS4xOTUuMjQyLTEuNzg1LjI1Ny4wMTUuMDguMDg3LjA2NC4xNC4wOC40NzYuMTU0IDEuMDIuMjQ1IDEuNTE2LjMyLjA2OC4wNTItLjAwNi4wNzQtLjA2LjA4MS0uNDQ4LjA1OC0uOTIzLjE0My0xLjM3LjE2Ni0xLjI3LjA2NC0yLjU1LS4wNjgtMy43NzctLjM4bC0uNjktMS45NTdjLS4wNi4wMDYtLjA2My4wNi0uMDc5LjEwMy0uMDYuMTctLjMwNSAxLjQxNy0uMzg3IDEuNDM1LS42Ni0uMi0xLjI1MS0uNjQ3LTEuNzM2LTEuMTMybDEuMTUtMi4wNi0xLjgzNSAxLjAxMWMtLjI1OC0uNTgzLS4zMDUtMS4yNDMtLjIxOS0xLjg3bDIuMzc1LTEuMThjLS43MzktLjA0OS0xLjQ4Ni4wNjgtMi4yMi4xNDUuMTI1LS4zNi4yNzctLjcxOC40NjItMS4wNTEuMDY3LS4xMjIuNDI2LS43MjEuNTItLjcyNC44Ni4xNjQgMS43ODYuMjQxIDIuNjQ4LjA3NGwtMS44Ny0uNzcxLS4wNjktLjA5M2MuMzgyLS4zNi43Ny0uNzE3IDEuMTk5LTEuMDI0LjgwNC4yMzQgMS42My40MjIgMi40NzMuNDMzTDkuMzUgOS4zNDJhNyA3IDAgMCAxIC41NjctLjQwMWMuMTYtLjEwMy42MDktLjQwMi43NzItLjM4LjY1LjIyMSAxLjMyNC4zNzggMi4wMS40MzMtLjMxMy0uMzI1LS45MDktLjU2NC0xLjIxLS44NjgtLjAzMy0uMDM0LS4wNTgtLjAzNi0uMDQzLS4wOTguNzg3LS40NTIgMS42NjItLjkwMSAyLjM0LTEuNTE3LjY5LS42MjkgMS40MjEtMS42NTYuOTI0LTIuNjA1LjU3My4xODIgMS4wNjcuOTA2IDEuMDU0IDEuNTEyLS4wMzQgMS42NzYtMS44MjIgMy4xNy0yLjk0MyA0LjIyMiAxLjczMi0uNzI4IDMuNzE0LTIuMjMgMy43MS00LjMwNS0uMDAzLTEuNjg4LTEuNTQtMi4zNjUtMi45OTMtMi41MThhMy4yIDMuMiAwIDAgMS0uMzg1IDEuMDg3Yy0uNDI4LjcxOS0xLjMwMiAxLjE2OC0xLjc1OCAxLjkxNS0uMzExLjUxLS4zNyAxLjE5NS0xLjAzMSAxLjM5LS4yNy4wOC0uNjE3LjA5My0uODk3LjA5NGwuNjE1LS4zMjVjLjY4OS0uNTA2LjY3Ny0xLjQyIDEuMDk5LTIuMS0uMDUtLjA3LS41NDUtLjItLjY2LS4yMjktLjUxLS4xMjUtMS4zNzUtLjI4NS0xLjg4Ni0uMjUtLjE1Ny4wMS0uODY5LjEyMS0uOTMuMjQyLS4wODguMTc3LjM0MS45My40NjggMS4xMDEuMDI1LjAzNS4wNzcuMDI2LjA4LjAzLjAyNC4wMzEuMDA3LjEwNS0uMDYuMDhhNSA1IDAgMCAxLS40MDQtLjI4M2MtLjUwMy0uMzg4LTEuMDc4LS45NzQtMS40OTktMS40NDctLjA2OC0uMTY2LS4xNi0uMzUuMDAyLS40ODcuODg4LS41NSAxLjc2OC0xLjEyNiAyLjY3LTEuNjUxIDIuNjcxLTEuNTU4IDUuNzExLTMuMzE4IDguMjY3LS40NjUgMi4xMTkgMi4zNjYgMS41MTQgNS4yMTItLjUxMiA3LjM3MnptLTguMjI0LTUuMzhjLjY5OS0uMTIyIDIuMDE4LjU3MiAyLjIzNS0uNDU2LjAyMS0uMS0uMDM2LS4xNTcuMDItLjI1NS4wNDMtLjA3My4yODYtLjI1LjM3LS4zMTguMjctLjIxNy41NzctLjM4Ny44NDItLjYxMi0xLjAyOS4xNjYtMi4wNjUuNzU2LTIuOTY0IDEuMjc3LS4xNDkuMDg2LS4zMS4xNzYtLjQ1MS4yNzMtLjAzNy4wMjUtLjA3NS0uMDA2LS4wNTMuMDltLTQuODMgMTAuODQ0Yy0xLjcxNSAxLjg4MS0xLjMyNSA0LjU3LjQ5NCA2LjIxNyAxLjgxMSAxLjY0MSA0LjY2IDIuMjIzIDcuMDQ4IDIuMTA4IDIuMTUyLS4xMDMgNC4zMzctLjgxMiA2LjQ2LS4wOTEuODI1LjI4IDEuNTQ2LjgwNSAyLjE2IDEuNDExLS4wODMtLjQtLjMyNC0uODE5LS41NTgtMS4xNTktMi4xMy0zLjA5NS02LjI3LTEuOTM1LTkuNDI2LTIuNTUzLTEuNzExLS4zMzUtMy40OTEtMS4xMTgtNC41MzMtMi41NjctLjkwMS0xLjI1My0xLjA0Mi0yLjczLS41OTUtNC4xOTQtLjA5MS0uMDktLjk1Mi43MjEtMS4wNS44MjhtNi4zNjYtOC42NjdjLS4zODIuMzM5LS43ODcuNjYtMS4yMTIuOTQ4bC0xLjIwNy41OWMxLjAyMi4wMzkgMi4wOC0uNTQ2IDIuNDItMS41MzciLz48L3N2Zz4=" alt="mulgadc.com"></a>
+  <a href="https://mulgadc.com"><img src="https://img.shields.io/badge/Site-mulga-orange?style=flat-square&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9IiNmZmYiIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTE2LjcxOCA4Ljg5MWMtMS4yODUgMS4zNy0zLjE3OCAyLjMxNy00LjY5NSAzLjQ0LS44NTQuNjMtMy4wODkgMi4yNy0xLjYxIDMuMzQ0IDEuNzg4IDEuMjk4IDYuMjQzLjE2NCA3Ljc4NS0xLjI2Ljg0LS43NzUuODE0LTEuODIyLS4zMjgtMi4yNTktMS4yMzUtLjQ3Mi0yLjY2LS4xMTEtMy45MTMuMDg3LS4wNDIuMDA3LS4xMzEuMDU1LS4xMjMtLjAyLjUyMy0uMzM2Ljk5My0uNzUgMS41MDMtMS4xMDIuNDkyLS4zNCAxLjA5Ny0uODI3IDEuNy0uODM4IDEuODcxLS4wMzQgMy43OTkuODkgNC4yODcgMi44MTUuODExIDMuMjAzLTMuMDA2IDUuNzE1LTUuNzg0IDUuOTQybDEuNjE0LS43NDdjLjYwNS0uMzYgMS4yMTctLjczNCAxLjc1Mi0xLjE5Ni4xMzMtLjExNS4yMy0uMjYzLjM0Mi0uMzczLjAyNy0uMDI2LjMwMi0uMTQ0LjE0NC0uMTUtMS40NDEuOTQ1LTMuMTI3IDEuNTcyLTQuODEzIDEuOTMyLS41OC4xMjMtMS4xOTUuMjQyLTEuNzg1LjI1Ny4wMTUuMDguMDg3LjA2NC4xNC4wOC40NzYuMTU0IDEuMDIuMjQ1IDEuNTE2LjMyLjA2OC4wNTItLjAwNi4wNzQtLjA2LjA4MS0uNDQ4LjA1OC0uOTIzLjE0My0xLjM3LjE2Ni0xLjI3LjA2NC0yLjU1LS4wNjgtMy43NzctLjM4bC0uNjktMS45NTdjLS4wNi4wMDYtLjA2My4wNi0uMDc5LjEwMy0uMDYuMTctLjMwNSAxLjQxNy0uMzg3IDEuNDM1LS42Ni0uMi0xLjI1MS0uNjQ3LTEuNzM2LTEuMTMybDEuMTUtMi4wNi0xLjgzNSAxLjAxMWMtLjI1OC0uNTgzLS4zMDUtMS4yNDMtLjIxOS0xLjg3bDIuMzc1LTEuMThjLS43MzktLjA0OS0xLjQ4Ni4wNjgtMi4yMi4xNDUuMTI1LS4zNi4yNzctLjcxOC40NjItMS4wNTEuMDY3LS4xMjIuNDI2LS43MjEuNTItLjcyNC44Ni4xNjQgMS43ODYuMjQxIDIuNjQ4LjA3NGwtMS44Ny0uNzcxLS4wNjktLjA5M2MuMzgyLS4zNi43Ny0uNzE3IDEuMTk5LTEuMDI0LjgwNC4yMzQgMS42My40MjIgMi40NzMuNDMzTDkuMzUgOS4zNDJhNyA3IDAgMCAxIC41NjctLjQwMWMuMTYtLjEwMy42MDktLjQwMi43NzItLjM4LjY1LjIyMSAxLjMyNC4zNzggMi4wMS40MzMtLjMxMy0uMzI1LS45MDktLjU2NC0xLjIxLS44NjgtLjAzMy0uMDM0LS4wNTgtLjAzNi0uMDQzLS4wOTguNzg3LS40NTIgMS42NjItLjkwMSAyLjM0LTEuNTE3LjY5LS42MjkgMS40MjEtMS42NTYuOTI0LTIuNjA1LjU3My4xODIgMS4wNjcuOTA2IDEuMDU0IDEuNTEyLS4wMzQgMS42NzYtMS44MjIgMy4xNy0yLjk0MyA0LjIyMiAxLjczMi0uNzI4IDMuNzE0LTIuMjMgMy43MS00LjMwNS0uMDAzLTEuNjg4LTEuNTQtMi4zNjUtMi45OTMtMi41MThhMy4yIDMuMiAwIDAgMS0uMzg1IDEuMDg3Yy0uNDI4LjcxOS0xLjMwMiAxLjE2OC0xLjc1OCAxLjkxNS0uMzExLjUxLS4zNyAxLjE5NS0xLjAzMSAxLjM5LS4yNy4wOC0uNjE3LjA5My0uODk3LjA5NGwuNjE1LS4zMjVjLjY4OS0uNTA2LjY3Ny0xLjQyIDEuMDk5LTIuMS0uMDUtLjA3LS41NDUtLjItLjY2LS4yMjktLjUxLS4xMjUtMS4zNzUtLjI4NS0xLjg4Ni0uMjUtLjE1Ny4wMS0uODY5LjEyMS0uOTMuMjQyLS4wODguMTc3LjM0MS45My40NjggMS4xMDEuMDI1LjAzNS4wNzcuMDI2LjA4LjAzLjAyNC4wMzEuMDA3LjEwNS0uMDYuMDhhNSA1IDAgMCAxLS40MDQtLjI4M2MtLjUwMy0uMzg4LTEuMDc4LS45NzQtMS40OTktMS40NDctLjA2OC0uMTY2LS4xNi0uMzUuMDAyLS40ODcuODg4LS41NSAxLjc2OC0xLjEyNiAyLjY3LTEuNjUxIDIuNjcxLTEuNTU4IDUuNzExLTMuMzE4IDguMjY3LS40NjUgMi4xMTkgMi4zNjYgMS41MTQgNS4yMTItLjUxMiA3LjM3MnptLTguMjI0LTUuMzhjLjY5OS0uMTIyIDIuMDE4LjU3MiAyLjIzNS0uNDU2LjAyMS0uMS0uMDM2LS4xNTcuMDItLjI1NS4wNDMtLjA3My4yODYtLjI1LjM3LS4zMTguMjctLjIxNy41NzctLjM4Ny44NDItLjYxMi0xLjAyOS4xNjYtMi4wNjUuNzU2LTIuOTY0IDEuMjc3LS4xNDkuMDg2LS4zMS4xNzYtLjQ1MS4yNzMtLjAzNy4wMjUtLjA3NS0uMDA2LS4wNTMuMDltLTQuODMgMTAuODQ0Yy0xLjcxNSAxLjg4MS0xLjMyNSA0LjU3LjQ5NCA2LjIxNyAxLjgxMSAxLjY0MSA0LjY2IDIuMjIzIDcuMDQ4IDIuMTA4IDIuMTUyLS4xMDMgNC4zMzctLjgxMiA2LjQ2LS4wOTEuODI1LjI4IDEuNTQ2LjgwNSAyLjE2IDEuNDExLS4wODMtLjQtLjMyNC0uODE5LS41NTgtMS4xNTktMi4xMy0zLjA5NS02LjI3LTEuOTM1LTkuNDI2LTIuNTUzLTEuNzExLS4zMzUtMy40OTEtMS4xMTgtNC41MzMtMi41NjctLjkwMS0xLjI1My0xLjA0Mi0yLjczLS41OTUtNC4xOTQtLjA5MS0uMDktLjk1Mi43MjEtMS4wNS44MjhtNi4zNjYtOC42NjdjLS4zODIuMzM5LS43ODcuNjYtMS4yMTIuOTQ4bC0xLjIwNy41OWMxLjAyMi4wMzkgMi4wOC0uNTQ2IDIuNDItMS41MzciLz48L3N2Zz4=" alt="mulgadc.com"></a>
+  <a href="https://docs.mulgadc.com"><img src="https://img.shields.io/badge/Docs-spinifex-0969da?style=flat-square&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9IiNmZmYiIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTYuNSAySDIwYTEgMSAwIDAgMSAxIDF2MTQuNWExIDEgMCAwIDEtMSAxSDYuNWExLjUgMS41IDAgMCAwIDAgM0gyMWExIDEgMCAwIDEgMCAySDYuNUEzLjUgMy41IDAgMCAxIDMgMjBWNS41QTMuNSAzLjUgMCAwIDEgNi41IDJ6bTEgNGExIDEgMCAwIDAgMCAyaDlhMSAxIDAgMCAwIDAtMmgtOXptMCA0YTEgMSAwIDAgMCAwIDJoOWExIDEgMCAwIDAgMC0yaC05eiIvPjwvc3ZnPg==" alt="docs.mulgadc.com"></a>
 </p>
 
+
 <p align="center">
-  <a href="#what-is-spinifex">What is Spinifex?</a> ·
-  <a href="#the-platform">Platform</a> ·
-  <a href="#three-ways-to-deploy">Deploy</a> ·
-  <a href="#aws-compatibility">AWS Compatibility</a> ·
-  <a href="#live-demo">Live Demo</a> ·
-  <a href="#core-components">Components</a> ·
-  <a href="#architecture-at-a-glance">Architecture</a> ·
-  <a href="#self-hosted-installation">Installation</a> ·
-  <a href="https://docs.mulgadc.com">Docs</a>
+  <a href="#try-it-live">Live Demo</a> ·
+  <a href="#services">Services</a> ·
+  <a href="#deploy-anywhere">Deploy</a> ·
+  <a href="#install">Install</a> ·
+  <a href="#architecture">Architecture</a>
 </p>
 
 ---
 
 # Spinifex: the open, AWS-compatible cloud you run yourself
 
-Spinifex, built by [Mulga](https://mulgadc.com), recreates the AWS services your software already uses (EC2, EBS, S3, VPC, IAM) on infrastructure you control. Move workloads off the hyperscalers, run AI at a fraction of the cost, or take the cloud to the edge, without rewriting a line. The exact build you ship to AWS, Spinifex serves on your own hardware: same APIs, same Terraform, same SDKs.
+Spinifex, built by [Mulga](https://mulgadc.com), recreates the AWS services your software already uses on infrastructure you control. Move workloads off the hyperscalers, run AI at a fraction of the cost, or take the cloud to the edge, without rewriting a line.
 
-## What is Spinifex?
-
-Spinifex is an open-source infrastructure platform that recreates the AWS service surface (EC2, EBS, S3, VPC, IAM) on bare-metal, edge, and on-premises environments. Run cloud-native software without a hyperscaler.
-
-Built for teams that need:
-
-- The AWS tooling you already use (AWS CLI, SDKs, Terraform), with nothing to rewrite
-- Full control of the stack: your hardware, your network, your data, your keys
-- A cloud that keeps running offline, through disconnection, with no external control plane
-- An open core (AGPL-3.0), auditable and yours to keep, with no lock-in
+- **Your AWS tooling, unchanged.** The AWS CLI, SDKs, and Terraform work as they are.
+- **Full control of the stack.** Your hardware, data, and keys, with no external control plane, running through disconnection.
+- **Open core under AGPL-3.0.** Auditable, yours to keep, with no lock-in.
 
 You change *where* your software runs, not *what* it is.
 
-## The Platform
+## Try It Live
+
+Get a real Spinifex endpoint in under a minute, with no card and no install. The sandbox is yours for 72 hours, with access keys, the web console, and EC2, EBS, S3, VPC, IAM, EKS, and RDS ready to call. Point your existing AWS CLI or Terraform straight at it.
+
+**[Create your sandbox →](https://mulgadc.com/signup)**
+
+## Same Commands, Your Cloud
+
+```bash
+export AWS_PROFILE=spinifex
+aws ec2 describe-images
+aws ec2 run-instances --image-id ami-xxxxxxxx --instance-type t3.micro
+aws s3 mb s3://my-bucket
+```
+
+For Terraform, start from the [example workbooks](https://docs.mulgadc.com/docs/nginx-webserver).
+
+## Why Not LocalStack or Floci?
+
+[LocalStack](https://github.com/localstack/localstack) and [Floci](https://github.com/floci-io/floci) are emulators for local development and CI testing. An emulator returns a plausible response; Spinifex boots the machine. A call launches a real KVM guest, attaches a replicated Viperblock volume, or writes an erasure-coded object into Predastore, so Spinifex can run your production workloads on hardware you own. Test against an emulator, then run in production on Spinifex.
+
+## Services
+
+The platform serves **392 AWS API operations** across the services below. See exactly which ones in the [coverage report](https://docs.mulgadc.com/coverage).
+
+| Service | What it is | Built on | Status |
+| --- | --- | --- | --- |
+| **EC2** | Compute | QEMU/KVM, with spot instances and GPU passthrough | Available |
+| **EBS** | Block storage | [Viperblock](https://github.com/mulgadc/viperblock): replicated, with a WAL on local NVMe | Available |
+| **S3** | Object storage | [Predastore](https://github.com/mulgadc/predastore): Reed-Solomon erasure coding | Available |
+| **VPC** | Networking | OVN, with security groups | Available |
+| **IAM** | Identity & auth | SigV4 across every service | Available |
+| **ALB / NLB** | Load balancers | HAProxy (L7), nginx `stream` (L4), with ACM certificates | Available |
+| **EKS** | Kubernetes | k3s, with HA control planes and managed node groups | Available |
+| **ECR** | Container registry | Predastore, deduplicated per account | Available |
+| **ECS** | Container service | Spinifex instances | Available |
+| **RDS** | Databases | PostgreSQL and MariaDB, with automated backups | Available |
+| **Bedrock** | AI deployment | vLLM for text generation and Hugging Face TEI for embeddings and reranking | Q4 2026 |
+| **Lambda** | Serverless functions | | Q1 2027 |
+
+Roadmap services ship under the same AWS API surface, so code written for AWS today works the moment they land. [Track what's shipped in the release notes](https://github.com/mulgadc/spinifex/releases).
+
+## Deploy Anywhere
 
 <p align="center">
   <img src=".github/assets/platform.svg" alt="The Spinifex stack: your apps and AWS tooling on top, the Spinifex AWS-compatible service layer, running on standard Linux on CPU and GPU hardware, deployable to Neocloud, on-premise, or the edge." width="900">
 </p>
 
-From commodity hardware up to unmodified AWS tooling, every layer is replaceable and yours to own.
+- **Neocloud:** lift and shift onto partner GPU capacity (H100 / H200 / B200). Change an endpoint, keep the software.
+- **On-premise:** a multi-node HA cluster in your own data centre, so the stack, the data, and the jurisdiction stay yours.
+- **Edge:** air-gapped sites, vehicles, vessels, factories, and clinics, with compute next to the data.
 
-## Three Ways To Deploy
+## Install
 
-The same AWS-compatible platform runs in three shapes. Pick the one that matches your hardware.
+Spinifex runs on Ubuntu 26.04 or Debian 13. The full guides are at [docs.mulgadc.com](https://docs.mulgadc.com).
 
-### Neocloud
+>*Prerequisite:* Spinifex requires a Linux bridge configured on the host for VM networking. See the [single-node install guide](https://docs.mulgadc.com/docs/install#prerequisites) for setup details.
 
-Lift and shift onto a partner Neocloud without rewriting workloads. GPU capacity (H100 / H200 / B200), cheaper, available now. Change an endpoint, keep the software.
-
-### On-premise
-
-Host Spinifex on your own hardware in your own data centre. You get a multi-node HA cluster integrated with your storage and networking, so the stack, the data, and the jurisdiction stay yours.
-
-### Edge
-
-Cloud where the cloud can't reach. Air-gapped sites, vehicles, vessels, factories, and clinics. Compute next to the data, running through disconnection, on hardware you own. The same AWS APIs your software already uses.
-
-## AWS Compatibility
-
-Spinifex speaks the AWS API surface. The AWS SDKs, AWS CLI, and Terraform all work unchanged, whether you deploy at the edge, on-premise, or on a partner Neocloud.
-
-| Service | What it is | Status |
-| --- | --- | --- |
-| **EC2** | Compute | Available |
-| **EBS** | Block Storage | Available |
-| **S3** | Object Storage | Available |
-| **VPC** | Networking | Available |
-| **IAM** | Identity & Auth | Available |
-| **ALB / NLB** | Load Balancers | Available |
-| **EKS** | Kubernetes | Available |
-| **ECR** | Container Registry | Available |
-| **ECS** | Container Service | Available |
-| **RDS** | Databases | Available |
-| **Bedrock** | AI Deployment | Q3 2026 |
-
-Roadmap items ship under the same AWS API surface. Code written for AWS today keeps working the moment they land. [Track what's shipped in the release notes](https://github.com/mulgadc/spinifex/releases).
-
-## Live Demo
-
-Create a live sandbox in under a minute. The fastest way to experience the stack. Try Spinifex against one of your own workloads on infrastructure we run for you.
-
-* Live in under a minute. No card, no install.
-* Yours for 72 hours to test and experiment.
-* Real AWS-compatible endpoint, access keys and console.
-* EC2, EBS, S3, VPC, IAM, EKS and RDS, ready to call.
-* Point your existing AWS CLI or Terraform straight at it.
-
-Sign up at [https://mulgadc.com/signup](https://mulgadc.com/signup)
-
-## Core Components
-
-### Spinifex (Compute and Platform Services – EC2, EKS, ECS, RDS)
-
-Spinifex is a minimal VM orchestration layer built on top of QEMU, exposing an EC2 compatible API. It manages lifecycle operations like start, stop, and terminate through QEMU's QMP interface. Designed to be straightforward and scriptable, Spinifex lets you launch VMs with the AWS CLI, SDKs, or Terraform, without Kubernetes or a heavyweight orchestrator.
-
-The managed services build on that same instance layer. An EKS node group, an ECS container instance, and an RDS database are Spinifex VMs on your own hardware, each driven through its own AWS API.
-
-- **EC2** – VM lifecycle on bare metal, cloud-init and IMDS metadata, key pairs, tags, spot instances, capacity reservations, and GPU passthrough
-- **EKS** – Managed Kubernetes on k3s, with HA control planes, managed node groups, cluster add-ons, an OIDC provider, and IAM access entries
-- **ECS** – Task and service scheduling across container instances, with awsvpc ENIs, capacity providers, rolling deployments, and GPU-aware placement
-- **ECR** – Private container registry backed by Predastore, with content-addressed blobs deduplicated per account and lifecycle policies
-- **RDS** – Managed PostgreSQL and MariaDB, with parameter groups, automated backups, and DNS endpoints served by Northstar
-- **ALB / NLB** – Layer 7 load balancing on HAProxy and layer 4 on nginx `stream`, with health checks and ACM-issued listener certificates
-- **VPC and IAM** – OVN-backed networking and security groups, with roles, policies, and SigV4 auth applied across every service
-
-### Viperblock (Block Storage – EBS Alternative)
-
-[Viperblock](https://github.com/mulgadc/viperblock) is a high-performance, WAL-backed block storage service that replicates volumes across multiple nodes. It's built for reliability and speed, with support for snapshots, recovery, and direct connection to QEMU instances using NBD or virtio-blk.
-
-- Fast, durable virtual disks
-- Replication for resilience
-- Exposed over NBD or embedded in VMs
-- High performance WAL logs on local NVMe drives, reducing IO traffic to S3
-- In-memory read/write block cache
-
-### Predastore (Object Storage – S3-Compatible)
-
-[Predastore](https://github.com/mulgadc/predastore) is a fully S3-compatible object storage system. It supports the AWS S3 API, including Signature V4 authentication, multipart uploads, and Terraform provisioning. Predastore chunks data and distributes it across nodes using Reed-Solomon erasure coding, so it survives node loss and suits large-scale or low-bandwidth sites.
-
-- S3-compatible API and auth
-- Multipart uploads, streaming reads/writes
-- Data redundancy with Reed-Solomon encoding
-
-### Northstar (Authoritative DNS)
-
-[Northstar](https://github.com/mulgadc/northstar) is a lightweight authoritative DNS server that handles both internal service discovery and public-facing DNS for a Spinifex cluster. Zones are human-readable TOML files, served from the local filesystem or synced from Predastore, keeping DNS configuration in the same object storage as the rest of your infrastructure.
-
-- Authoritative DNS over UDP, TCP, and DNS-over-TLS
-- Service discovery for cluster components via SRV records
-- Zone files stored locally or in S3-compatible storage
-
-## Architecture at a Glance
-
-<p align="center">
-  <img src=".github/assets/architecture.svg" alt="Spinifex message-driven architecture: standard AWS clients call the AWS Gateway over HTTPS with SigV4, which publishes to a NATS bus answered by stateless ec2/ebs/s3/vpc/iam daemons over local backends." width="900">
-</p>
-
-Every AWS API call is authenticated at the gateway, published to a NATS subject, and answered by whichever daemon claims it. Daemons are stateless: scale horizontally by starting more. No etcd, no Kubernetes, no external control plane. Just systemd units, a NATS cluster, and your hardware. Deep dive: **[`docs/DESIGN.md`](docs/DESIGN.md)**.
-
-## Self-hosted Installation
-
-Installation requires an Ubuntu 26.04 or Debian 13 system. See the detailed documentation at [docs.mulgadc.com](https://docs.mulgadc.com) for installing Spinifex.
-
-### Bare Metal ISO
-
-The recommended installation is a [bootable x86 installer](https://iso.mulgadc.com/spinifex.iso) for bare-metal hardware.
+**Bare metal (recommended):** download the [bootable x86 installer](https://iso.mulgadc.com/spinifex.iso) and follow the [USB install guide](https://docs.mulgadc.com/docs/install-usb).
 
 ```bash
 curl -fLO https://iso.mulgadc.com/spinifex.iso
 ```
 
-Follow the [USB install guide](https://docs.mulgadc.com/docs/install-usb) to write the ISO to USB and install on your hardware.
-
-### Single Node Install
-
->*Prerequisite:* Spinifex requires a Linux bridge configured on the host for VM networking. See the [single-node install guide](https://docs.mulgadc.com/docs/install#prerequisites) for setup details.
+**Single node:**
 
 ```bash
 curl -fsSL https://install.mulgadc.com | bash
-
 sudo /usr/local/share/spinifex/setup-ovn.sh --management
-
 sudo spx admin init --node node1 --nodes 1
-
 sudo systemctl start spinifex.target
-
 export AWS_PROFILE=spinifex
-
 aws ec2 describe-instance-types
 ```
 
-### Development Setup
+**From source:** see the [Source Install](https://docs.mulgadc.com/docs/install-source) guide.
 
-For a complete development environment see the [Source Install](https://docs.mulgadc.com/docs/install-source) documentation.
-
-## Spinifex UI
-
-Spinifex ships with a built-in web console, an optional alternative to the AWS CLI, SDKs, and Terraform. If you know the AWS Management Console, the Spinifex UI fills the same role: a browser-based view of your instances, volumes, buckets, VPCs, and IAM resources, without leaving your own network.
+## Web Console
 
 <p align="center">
   <img src=".github/assets/spinifex-ui.jpg" alt="Spinifex web console dashboard" width="900">
 </p>
 
-Each node serves the console on port `3000` over TLS, and it comes up with `spinifex.target`:
+Spinifex ships with a built-in web console for your instances, volumes, buckets, networks, and IAM. See [Launching the Web UI](https://docs.mulgadc.com/docs/setting-up-your-cluster#7-launching-the-web-ui).
 
-- **Same API, different surface.** The UI issues the same AWS SigV4 calls the CLI does, so RBAC, audit trails, and IAM policies apply the same way.
-- **Single sign-on against your AWS credentials.** Log in with the access keys from `~/.aws/credentials` on the node where Spinifex is installed. There is no separate user database.
-- **Self-hosted, works offline.** The Spinifex binary embeds the UI and each node serves it directly, with no external CDN or analytics calls.
+## Architecture
 
-For the full walkthrough, covering first-time TLS certificate trust, login, and a feature tour, see [**Launching the Web UI**](https://docs.mulgadc.com/docs/setting-up-your-cluster#7-launching-the-web-ui) in the cluster setup guide.
+<p align="center">
+  <img src=".github/assets/architecture.svg" alt="Spinifex message-driven architecture: standard AWS clients call the AWS Gateway over HTTPS with SigV4, which publishes to a NATS bus answered by stateless ec2/ebs/s3/vpc/iam daemons over local backends." width="900">
+</p>
 
-## Development Philosophy
+Every AWS API call is authenticated at the gateway, published to a NATS subject, and answered by whichever daemon claims it. Daemons are stateless, so you scale horizontally by starting more. Deep dive: **[`docs/DESIGN.md`](docs/DESIGN.md)**.
 
-### Built by Engineers, For Engineers
+## How We Build Spinifex
 
-Spinifex is developed by experienced infrastructure engineers with deep AWS expertise, including former AWS team members who understand the intricacies of building production-grade cloud services. Our team brings decades of combined experience from AWS, enterprise infrastructure, and edge computing environments.
+Spinifex is built by infrastructure engineers with deep AWS experience, including former AWS team members, drawing on decades of combined work across AWS, enterprise infrastructure, and edge computing. Engineers architect and implement it, with **Claude Code** accelerating parts of the work.
 
-### AI-Assisted Development
-
-Spinifex is architected and implemented by experienced engineers, with **Claude Code** accelerating certain development tasks. The split keeps the quality and reliability standards that production infrastructure demands:
-
-**How We Use Claude Code:**
-
-- **Code Generation**: Boilerplate AWS API structures and handlers
-- **Documentation**: Comprehensive development guides and API documentation
-- **Testing**: Test case generation and validation scenarios
-- **Refactoring**: Large-scale code restructuring and optimization
-
-**What Remains Human-Driven:**
-
-- **Architecture Decisions**: Core system design and scalability choices
-- **Security Implementation**: Authentication, encryption, and threat modeling
-- **Performance Optimization**: Real-world performance tuning and benchmarking
-- **Production Operations**: Deployment strategies and operational procedures
+| Claude Code assists with | Engineers own |
+| --- | --- |
+| Boilerplate AWS API structures and handlers | Architecture and scalability decisions |
+| Development guides and API documentation | Authentication, encryption, and threat modelling |
+| Test case generation and validation scenarios | Real-world performance tuning and benchmarking |
+| Large-scale restructuring and refactoring | Deployment strategy and production operations |
 
 ## Trademarks
 
@@ -227,4 +141,4 @@ Spinifex is architected and implemented by experienced engineers, with **Claude
 
 ## License
 
-Spinifex is open source under the [GNU Affero General Public License v3.0](LICENSE), with a commercial license available. You're free to use, modify, and deploy it anywhere you need reliable infrastructure without depending on centralized cloud platforms.
+Spinifex is open source under the [GNU Affero General Public License v3.0](LICENSE), with a commercial license available.

SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for a security vulnerability.
+
+Report it privately, either way works:
+
+- [Open a private security advisory](https://github.com/mulgadc/spinifex/security/advisories/new) on this repository.
+- Email <security@mulgadc.com>.
+
+Please include enough for us to reproduce it: the version or commit, the configuration involved, and the steps that trigger it. If you have a proof of concept, include that too.
+
+## What Happens Next
+
+We aim to acknowledge a report within three business days. We will confirm whether we can reproduce it, agree a fix and a disclosure timeline with you, and credit you in the advisory unless you would rather we did not.
+
+## Scope
+
+Spinifex is one part of the [Mulga](https://mulgadc.com) stack. If a vulnerability spans more than one component, report it once against whichever repository you found it in and we will handle the rest.
+
+## Supported Versions
+
+Fixes land on the latest release and on `main`. Older releases are not patched.

architecture/instancestate/allowlist_test.go

@@ -0,0 +1,92 @@
+package instancestate
+
+// allowance is one recorded production consumer of raw instance state.
+type allowance struct {
+	File, Symbol string
+	Inv          string // inventory item in docs/PACKAGE_BOUNDARY_MIGRATION.md
+}
+
+// allowlist mirrors the ADR-0007 slice 0 inventory in
+// docs/PACKAGE_BOUNDARY_MIGRATION.md. It only shrinks: delete an entry as soon
+// as its use is gone, and never add one to make a new consumer pass.
+var allowlist = []allowance{
+	{File: "spinifex/daemon/daemon.go", Symbol: "daemon.LocalStatePath", Inv: "INV-01"},
+	{File: "spinifex/daemon/daemon.go", Symbol: "daemon.ReadLocalState", Inv: "INV-01"},
+	{File: "spinifex/daemon/daemon.go", Symbol: "daemon.MarshalLocalState", Inv: "INV-01"},
+	{File: "spinifex/daemon/daemon.go", Symbol: "daemon.WriteLocalStateBytes", Inv: "INV-01"},
+	{File: "spinifex/daemon/daemon.go", Symbol: "JetStreamManager.InitKVBucket", Inv: "INV-02"},
+	{File: "spinifex/daemon/daemon.go", Symbol: "JetStreamManager.InitTerminatedInstanceBucket", Inv: "INV-02"},
+	{File: "spinifex/daemon/daemon.go", Symbol: "JetStreamManager.WriteNodeMarkerBestEffort", Inv: "INV-03"},
+	{File: "spinifex/daemon/daemon.go", Symbol: "JetStreamManager.WriteRunningSet", Inv: "INV-03"},
+	{File: "spinifex/daemon/instance_record_repair.go", Symbol: "JetStreamManager.WriteRunningSet", Inv: "INV-03"},
+	{File: "spinifex/daemon/daemon.go", Symbol: "JetStreamManager.ListTerminatedInstances", Inv: "INV-04"},
+
+	{File: "spinifex/daemon/vm_adapters.go", Symbol: "JetStreamManager.LoadState", Inv: "INV-05"},
+	{File: "spinifex/daemon/vm_adapters.go", Symbol: "JetStreamManager.WriteStoppedInstance", Inv: "INV-05"},
+	{File: "spinifex/daemon/vm_adapters.go", Symbol: "JetStreamManager.LoadStoppedInstance", Inv: "INV-05"},
+	{File: "spinifex/daemon/vm_adapters.go", Symbol: "JetStreamManager.DeleteStoppedInstance", Inv: "INV-05"},
+	{File: "spinifex/daemon/vm_adapters.go", Symbol: "JetStreamManager.UpdateStoppedInstance", Inv: "INV-05"},
+	{File: "spinifex/daemon/vm_adapters.go", Symbol: "JetStreamManager.ClaimStoppedInstance", Inv: "INV-05"},
+	{File: "spinifex/daemon/vm_adapters.go", Symbol: "JetStreamManager.ListStoppedInstances", Inv: "INV-05"},
+	{File: "spinifex/daemon/vm_adapters.go", Symbol: "JetStreamManager.WriteTerminatedInstance", Inv: "INV-05"},
+	{File: "spinifex/daemon/vm_adapters.go", Symbol: "JetStreamManager.UpdateTerminatedInstance", Inv: "INV-05"},
+	{File: "spinifex/daemon/vm_adapters.go", Symbol: "JetStreamManager.ListTerminatedInstances", Inv: "INV-05"},
+	{File: "spinifex/daemon/vm_adapters.go", Symbol: "JetStreamManager.DeleteTerminatedInstance", Inv: "INV-05"},
+
+	{File: "spinifex/runtime/compute/vm/migrate.go", Symbol: "JetStreamManager.WriteStoppedInstance", Inv: "INV-06"},
+	{File: "spinifex/runtime/compute/vm/migrate.go", Symbol: "JetStreamManager.WriteTerminatedInstance", Inv: "INV-06"},
+	{File: "spinifex/runtime/compute/vm/shutdown.go", Symbol: "JetStreamManager.WriteTerminatedInstance", Inv: "INV-06"},
+	{File: "spinifex/runtime/compute/vm/orphan_qemu_reaper.go", Symbol: "JetStreamManager.ListTerminatedInstances", Inv: "INV-06"},
+	{File: "spinifex/runtime/compute/vm/teardown_reaper.go", Symbol: "JetStreamManager.ListTerminatedInstances", Inv: "INV-06"},
+	{File: "spinifex/runtime/compute/vm/teardown_reaper.go", Symbol: "JetStreamManager.UpdateTerminatedInstance", Inv: "INV-06"},
+	{File: "spinifex/runtime/compute/vm/teardown_reaper.go", Symbol: "JetStreamManager.DeleteTerminatedInstance", Inv: "INV-06"},
+
+	{File: "spinifex/domains/ec2/instance/service_impl.go", Symbol: "JetStreamManager.LoadStoppedInstance", Inv: "INV-07"},
+	{File: "spinifex/domains/ec2/instance/service_impl.go", Symbol: "JetStreamManager.UpdateStoppedInstance", Inv: "INV-07"},
+	{File: "spinifex/domains/ec2/instance/service_impl.go", Symbol: "JetStreamManager.ListStoppedInstances", Inv: "INV-07"},
+	{File: "spinifex/domains/ec2/instance/service_impl.go", Symbol: "JetStreamManager.ListTerminatedInstances", Inv: "INV-07"},
+	{File: "spinifex/domains/ec2/instance/service_impl.go", Symbol: "JetStreamManager.WriteStoppedInstance", Inv: "INV-07"},
+	{File: "spinifex/domains/ec2/instance/service_impl.go", Symbol: "JetStreamManager.ClaimStoppedInstance", Inv: "INV-07"},
+	{File: "spinifex/domains/ec2/instance/service_impl.go", Symbol: "JetStreamManager.WriteTerminatedInstance", Inv: "INV-07"},
+	{File: "spinifex/domains/ec2/instance/service_impl.go", Symbol: "JetStreamManager.DeleteStoppedInstance", Inv: "INV-07"},
+
+	{File: "spinifex/daemon/daemon_handlers_image.go", Symbol: "JetStreamManager.LoadStoppedInstance", Inv: "INV-08"},
+	{File: "spinifex/daemon/daemon_handlers_image.go", Symbol: "JetStreamManager.UpdateStoppedInstance", Inv: "INV-08"},
+
+	{File: "spinifex/daemon/instance_recovery.go", Symbol: "vm.InstanceRecord", Inv: "INV-10"},
+	{File: "spinifex/daemon/instance_recovery.go", Symbol: "JetStreamManager.ListInstanceRecords", Inv: "INV-10"},
+	{File: "spinifex/daemon/instance_recovery.go", Symbol: "JetStreamManager.ClaimRecoverableInstance", Inv: "INV-10"},
+	{File: "spinifex/daemon/instance_recovery.go", Symbol: "JetStreamManager.ReleaseRecoveredInstance", Inv: "INV-10"},
+	{File: "spinifex/daemon/instance_recovery.go", Symbol: "JetStreamManager.AbandonRecovery", Inv: "INV-10"},
+	{File: "spinifex/daemon/instance_recovery.go", Symbol: "JetStreamManager.LoadInstanceRecord", Inv: "INV-10"},
+
+	{File: "spinifex/daemon/dns_reconcile.go", Symbol: "daemon.InstanceRecordPrefix", Inv: "INV-11"},
+	{File: "spinifex/daemon/dns_reconcile.go", Symbol: "daemon.InstanceStateBucket", Inv: "INV-11"},
+	{File: "spinifex/daemon/dns_reconcile.go", Symbol: "JetStreamManager.ListInstanceRecords", Inv: "INV-11"},
+
+	{File: "spinifex/daemon/eni_orphan_reaper.go", Symbol: "vm.InstanceRecord", Inv: "INV-12"},
+	{File: "spinifex/daemon/eni_orphan_reaper.go", Symbol: "JetStreamManager.ListInstanceRecords", Inv: "INV-12"},
+	{File: "spinifex/daemon/eni_orphan_reaper.go", Symbol: "JetStreamManager.ListTerminatedInstanceRecords", Inv: "INV-12"},
+
+	{File: "spinifex/domains/ec2/instance/state/imds_readers.go", Symbol: "daemon.LocalState", Inv: "INV-13"},
+	{File: "spinifex/domains/ec2/instance/state/imds_readers.go", Symbol: "daemon.LocalStatePath", Inv: "INV-13"},
+	{File: "spinifex/domains/ec2/instance/state/imds_readers.go", Symbol: "daemon.ReadLocalState", Inv: "INV-13"},
+	{File: "spinifex/domains/ec2/instance/state/imds_readers.go", Symbol: "daemon.InstanceStateBucket", Inv: "INV-13"},
+	{File: "spinifex/domains/ec2/instance/state/imds_readers.go", Symbol: "JetStreamManager.InitKVBucket", Inv: "INV-13"},
+
+	{File: "spinifex/domains/ec2/guestmetadata/instance_lookup.go", Symbol: "vm.InstanceRecord", Inv: "INV-14"},
+	{File: "spinifex/domains/ec2/guestmetadata/instance_lookup.go", Symbol: "vm.VMFromRecord", Inv: "INV-14"},
+	{File: "spinifex/domains/ec2/guestmetadata/instance_lookup.go", Symbol: "JetStreamManager.LoadInstanceRecord", Inv: "INV-14"},
+
+	{File: "spinifex/domains/network/reconcile/intent.go", Symbol: `literal "spinifex-instance-state"`, Inv: "INV-15"},
+	{File: "spinifex/domains/network/reconcile/intent.go", Symbol: "vm.InstanceRecord", Inv: "INV-15"},
+
+	{File: "spinifex/runtime/roles/awsgw/awsgw.go", Symbol: "daemon.InstanceStateBucket", Inv: "INV-16"},
+	{File: "spinifex/runtime/roles/awsgw/awsgw.go", Symbol: "daemon.InstanceRecordPrefix", Inv: "INV-16"},
+	{File: "spinifex/runtime/roles/awsgw/awsgw.go", Symbol: "vm.InstanceRecord", Inv: "INV-16"},
+
+	{File: "spinifex/runtime/compute/cache/cache.go", Symbol: "vm.InstanceRecord", Inv: "INV-17"},
+	{File: "spinifex/runtime/compute/cache/cache.go", Symbol: "vm.VMFromRecord", Inv: "INV-17"},
+
+	{File: "spinifex/domains/admission/quota/records.go", Symbol: "vm.InstanceRecord", Inv: "INV-18"},
+}

architecture/instancestate/instancestate_test.go

@@ -0,0 +1,200 @@
+package instancestate
+
+import (
+	"fmt"
+	"go/parser"
+	"go/token"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+type report struct {
+	unrecorded []use
+	stale      []allowance
+	malformed  []string
+}
+
+// check compares the scanned uses with allow.
+func check(s scan, allow []allowance) report {
+	var rep report
+	allowed := map[use]bool{}
+	for _, a := range allow {
+		u := use{File: a.File, Symbol: a.Symbol}
+		switch {
+		case allowed[u]:
+			rep.malformed = append(rep.malformed, "duplicate entry "+u.String())
+		case a.Inv == "":
+			rep.malformed = append(rep.malformed, "entry "+u.String()+" cites no inventory item")
+		}
+		allowed[u] = true
+	}
+	for _, u := range s.sorted() {
+		if !allowed[u] {
+			rep.unrecorded = append(rep.unrecorded, u)
+		}
+	}
+	for _, a := range allow {
+		if _, ok := s[use{File: a.File, Symbol: a.Symbol}]; !ok {
+			rep.stale = append(rep.stale, a)
+		}
+	}
+	return rep
+}
+
+// TestADR0007_S6_NoNewRawInstanceStateConsumers is the blocking ratchet: no
+// production file may start naming the daemon's instance-state bucket, keys,
+// local file, raw record or JetStreamManager instance methods.
+func TestADR0007_S6_NoNewRawInstanceStateConsumers(t *testing.T) {
+	root, err := moduleRoot()
+	if err != nil {
+		t.Fatal(err)
+	}
+	s, files, err := scanModule(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Guards against a walk that silently finds nothing and passes vacuously.
+	if files < 500 || len(s) < 20 {
+		t.Fatalf("scanned %d files and found %d uses under %s; the walk has lost the tree", files, len(s), root)
+	}
+	if len(allowlist) == 0 {
+		t.Fatal("the allowlist is empty, so the stale check would pass vacuously")
+	}
+	rep := check(s, allowlist)
+
+	t.Run("NoUnrecordedConsumer", func(t *testing.T) {
+		for _, u := range rep.unrecorded {
+			t.Errorf("ADR-0007 S6 (consumers receive narrow state capabilities rather than raw stores): %s at %s; "+
+				"consume an instance-domain capability instead of the daemon's raw instance state", u, s[u])
+		}
+	})
+	t.Run("Allowlist_NoStaleEntries", func(t *testing.T) {
+		for _, a := range rep.stale {
+			t.Errorf("allowlist entry %s uses %s (%s) no longer matches; delete it and update the inventory",
+				a.File, a.Symbol, a.Inv)
+		}
+	})
+	t.Run("Allowlist_WellFormed", func(t *testing.T) {
+		for _, m := range rep.malformed {
+			t.Errorf("allowlist_test.go: %s", m)
+		}
+		t.Logf("%d allow-listed uses", len(allowlist))
+	})
+	t.Run("OwnerFilesExist", func(t *testing.T) {
+		for _, f := range ownerFiles {
+			if _, err := os.Stat(filepath.Join(root, f)); err != nil {
+				t.Errorf("owner file %s is gone; remove it from ownerFiles and re-scan its consumers: %v", f, err)
+			}
+		}
+	})
+}
+
+const faultSource = `package %s
+
+import (
+	"encoding/json"
+
+	spxd "github.com/mulgadc/spinifex/spinifex/daemon"
+	"github.com/mulgadc/spinifex/spinifex/runtime/compute/vm"
+)
+
+type holder struct {
+	LoadInstanceRecord func() // a field name, not a use
+	m                  *spxd.JetStreamManager
+}
+
+func (h holder) WriteRunningSet() {} // a declaration, not a use
+
+func use(h holder, raw []byte, jsManager *spxd.JetStreamManager, other interface{ LoadState() }) {
+	_ = spxd.InstanceStateBucket
+	_ = spxd.LocalStatePath("")
+	var r vm.InstanceRecord
+	_ = json.Unmarshal(raw, &r)
+	_ = vm.VMFromRecord(&r)
+	_ = (&vm.VM{}).Record()
+	_, _ = h.m.LoadInstanceRecord("i-1")
+	_, _, _ = jsManager.LoadState("node")
+	other.LoadState()
+	_ = "spinifex-instance-state"
+	cluster, _ := spxd.NewJetStreamManager(nil)
+	_ = cluster.InitClusterStateBucket()
+	_ = cluster.WriteRunningSet("node", nil)
+}
+`
+
+func parseFault(t *testing.T, rel, pkg string) scan {
+	t.Helper()
+	fset := token.NewFileSet()
+	f, err := parser.ParseFile(fset, rel, fmt.Sprintf(faultSource, pkg), parser.SkipObjectResolution)
+	if err != nil {
+		t.Fatal(err)
+	}
+	out := scan{}
+	scanFile(fset, rel, f, out)
+	return out
+}
+
+// TestADR0007_S6_RatchetDetectsFaults injects a new consumer, a stale entry
+// and a malformed entry, and checks the matcher's declaration exclusions.
+func TestADR0007_S6_RatchetDetectsFaults(t *testing.T) {
+	const rel = "spinifex/domains/widget/w.go"
+	s := parseFault(t, rel, "widget")
+
+	want := []string{
+		"daemon.InstanceStateBucket", "daemon.LocalStatePath",
+		"vm.InstanceRecord", "vm.VMFromRecord", "VM.Record()",
+		"JetStreamManager.LoadInstanceRecord", "JetStreamManager.LoadState",
+		"JetStreamManager.WriteRunningSet",
+		`literal "spinifex-instance-state"`,
+	}
+	for _, sym := range want {
+		if _, ok := s[use{File: rel, Symbol: sym}]; !ok {
+			t.Errorf("injected use of %s was not detected; got %v", sym, s.sorted())
+		}
+	}
+	if len(s) != len(want) {
+		t.Errorf("want exactly %d uses (the manager type, its constructor, cluster-state methods, field names, method declarations and an unrelated LoadState excluded), got %v",
+			len(want), s.sorted())
+	}
+
+	stale := allowance{File: "spinifex/domains/gone/g.go", Symbol: "vm.InstanceRecord", Inv: "INV-00"}
+	recorded := allowance{File: rel, Symbol: "vm.InstanceRecord", Inv: "INV-00"}
+	rep := check(s, []allowance{recorded, stale, {File: rel, Symbol: "vm.VMFromRecord"}, recorded})
+	if len(rep.unrecorded) != len(want)-2 {
+		t.Errorf("want %d unrecorded uses, got %v", len(want)-2, rep.unrecorded)
+	}
+	if len(rep.stale) != 1 || rep.stale[0] != stale {
+		t.Errorf("want stale entry %+v, got %+v", stale, rep.stale)
+	}
+	if len(rep.malformed) != 2 {
+		t.Errorf("want a missing-inventory and a duplicate entry reported, got %v", rep.malformed)
+	}
+}
+
+// Inside the owning packages the symbols are bare identifiers, and the scan
+// must see those too.
+func TestADR0007_S6_RatchetSeesBareIdentifiersInOwnerPackages(t *testing.T) {
+	src := map[string]string{
+		"spinifex/daemon/new_consumer.go":           "package daemon\n\nfunc f() string { return InstanceStateBucket + LocalStatePath(\"\") }\n",
+		"spinifex/runtime/compute/vm/new_reader.go": "package vm\n\nfunc g(r *InstanceRecord) *VM { return VMFromRecord(r) }\n",
+	}
+	want := map[string][]string{
+		"spinifex/daemon/new_consumer.go":           {"daemon.InstanceStateBucket", "daemon.LocalStatePath"},
+		"spinifex/runtime/compute/vm/new_reader.go": {"vm.InstanceRecord", "vm.VMFromRecord"},
+	}
+	for rel, code := range src {
+		fset := token.NewFileSet()
+		f, err := parser.ParseFile(fset, rel, code, parser.SkipObjectResolution)
+		if err != nil {
+			t.Fatal(err)
+		}
+		out := scan{}
+		scanFile(fset, rel, f, out)
+		for _, sym := range want[rel] {
+			if _, ok := out[use{File: rel, Symbol: sym}]; !ok {
+				t.Errorf("%s: bare use of %s not detected; got %v", rel, sym, out.sorted())
+			}
+		}
+	}
+}

architecture/instancestate/scan_test.go

@@ -0,0 +1,302 @@
+// Package instancestate freezes the production consumers of the daemon's raw
+// instance-state persistence, so ADR-0007 S6 and S7 start from a known set
+// that can only shrink.
+package instancestate
+
+import (
+	"errors"
+	"fmt"
+	"go/ast"
+	"go/build/constraint"
+	"go/parser"
+	"go/token"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"runtime"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+const (
+	daemonPath = "github.com/mulgadc/spinifex/spinifex/daemon"
+	vmPath     = "github.com/mulgadc/spinifex/spinifex/runtime/compute/vm"
+	daemonDir  = "spinifex/daemon"
+	vmDir      = "spinifex/runtime/compute/vm"
+)
+
+// daemonSymbols are the daemon's instance-state bucket, key and local-file
+// identifiers. The JetStreamManager type and constructor are not listed: they
+// also serve cluster state, so only the instance-state methods below count.
+var daemonSymbols = set(
+	"InstanceStateBucket", "InstanceStateBucketVersion",
+	"TerminatedInstanceBucket", "TerminatedInstanceBucketVersion",
+	"InstanceRecordPrefix", "InstanceStatePrefix", "NodePresencePrefix",
+	"StoppedInstancePrefix", "TerminatedInstancePrefix",
+	"LocalState", "LocalStateSchemaVersion", "LocalStatePath", "ReadLocalState",
+	"MarshalLocalState", "WriteLocalStateBytes", "LocalStateFileName",
+	"LocalStateFileMode", "DefaultLocalStateDir",
+)
+
+// vmSymbols are the raw persisted record and its conversion.
+var vmSymbols = set("InstanceRecord", "InstanceSpec", "InstanceStatus", "VMFromRecord")
+
+// jsmMethods are JetStreamManager's instance-state methods. Matched by name, so
+// a call through an interface that mirrors them counts as a consumer too.
+var jsmMethods = set(
+	"WriteInstanceRecord", "LoadInstanceRecord", "UpdateInstanceRecord",
+	"DeleteInstanceRecord", "ListInstanceRecords",
+	"WriteTerminatedInstanceRecord", "LoadTerminatedInstanceRecord",
+	"UpdateTerminatedInstanceRecord", "DeleteTerminatedInstanceRecord",
+	"ListTerminatedInstanceRecords",
+	"WriteNodeMarker", "WriteNodeMarkerBestEffort", "WriteRunningSet",
+	"WriteStoppedInstance", "LoadStoppedInstance", "DeleteStoppedInstance",
+	"ClaimStoppedInstance", "ClaimRecoverableInstance", "ReleaseRecoveredInstance",
+	"AbandonRecovery", "UpdateStoppedInstance", "ListStoppedInstances",
+	"WriteTerminatedInstance", "UpdateTerminatedInstance", "ListTerminatedInstances",
+	"DeleteTerminatedInstance", "LoadTerminatedInstance",
+	"InitKVBucket", "InitTerminatedInstanceBucket",
+)
+
+// ambiguousJSMMethods share a name with unrelated methods, so they count only
+// when called on a field or variable named like a JetStreamManager handle.
+var ambiguousJSMMethods = set("LoadState", "DeleteState")
+
+// literals duplicate a bucket or file name instead of naming the owner's symbol.
+var literals = set(`"spinifex-instance-state"`, `"spinifex-terminated-instances"`, `"instance-state.json"`)
+
+// ownerFiles define the symbols above. They are the implementation being
+// migrated, not consumers of it, and are listed so a deleted one is noticed.
+var ownerFiles = []string{
+	"spinifex/daemon/instance_membership.go",
+	"spinifex/daemon/instance_records.go",
+	"spinifex/daemon/instance_records_migrate.go",
+	"spinifex/daemon/instance_running_set.go",
+	"spinifex/daemon/jetstream.go",
+	"spinifex/daemon/local_state.go",
+	"spinifex/runtime/compute/vm/record.go",
+}
+
+func set(names ...string) map[string]bool {
+	m := make(map[string]bool, len(names))
+	for _, n := range names {
+		m[n] = true
+	}
+	return m
+}
+
+// use is one consumer of one symbol, keyed by file so a new file is a new use.
+type use struct {
+	File, Symbol string
+}
+
+func (u use) String() string { return u.File + " uses " + u.Symbol }
+
+// scan maps each use to the first file:line it appears at.
+type scan map[use]string
+
+func moduleRoot() (string, error) {
+	_, file, _, ok := runtime.Caller(0)
+	if !ok {
+		return "", errors.New("cannot locate test source")
+	}
+	return filepath.Abs(filepath.Join(filepath.Dir(file), "..", ".."))
+}
+
+var excludedTopDirs = map[string]bool{"tests": true, "docs": true, "architecture": true}
+
+// scanModule parses every non-test production Go file under root.
+func scanModule(root string) (scan, int, error) {
+	out := scan{}
+	files := 0
+	fset := token.NewFileSet()
+	owners := set(ownerFiles...)
+	err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		rel, err := filepath.Rel(root, path)
+		if err != nil {
+			return err
+		}
+		rel = filepath.ToSlash(rel)
+		if d.IsDir() {
+			if rel == "." {
+				return nil
+			}
+			name := d.Name()
+			if strings.HasPrefix(name, ".") || strings.HasPrefix(name, "_") ||
+				name == "testdata" || name == "vendor" || name == "node_modules" || excludedTopDirs[rel] {
+				return filepath.SkipDir
+			}
+			if _, err := os.Stat(filepath.Join(path, "go.mod")); err == nil {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+			return nil
+		}
+		src, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+		f, err := parser.ParseFile(fset, path, src, parser.ParseComments|parser.SkipObjectResolution)
+		if err != nil {
+			return err
+		}
+		if ignoredByBuildTag(f.Comments, f.Package) {
+			return nil
+		}
+		files++
+		if owners[rel] {
+			return nil
+		}
+		scanFile(fset, rel, f, out)
+		return nil
+	})
+	return out, files, err
+}
+
+// scanFile records every use in f, which lives at module-relative path rel.
+func scanFile(fset *token.FileSet, rel string, f *ast.File, out scan) {
+	dir := filepath.ToSlash(filepath.Dir(rel))
+	daemonName, vmName := importName(f, daemonPath, "daemon"), importName(f, vmPath, "vm")
+	inDaemon, inVM := dir == daemonDir, dir == vmDir
+	seesVM := inDaemon || inVM || daemonName != "" || vmName != ""
+
+	record := func(symbol string, pos token.Pos) {
+		u := use{File: rel, Symbol: symbol}
+		if _, ok := out[u]; !ok {
+			out[u] = fmt.Sprintf("%s:%d", rel, fset.Position(pos).Line)
+		}
+	}
+
+	var visit func(n ast.Node) bool
+	visit = func(n ast.Node) bool {
+		switch n := n.(type) {
+		case *ast.ImportSpec:
+			return false
+		case *ast.BasicLit:
+			if n.Kind == token.STRING && literals[n.Value] {
+				record("literal "+n.Value, n.Pos())
+			}
+		case *ast.CallExpr:
+			if sel, ok := n.Fun.(*ast.SelectorExpr); ok && sel.Sel.Name == "Record" && len(n.Args) == 0 && seesVM {
+				record("VM.Record()", sel.Sel.Pos())
+			}
+		case *ast.SelectorExpr:
+			if x, ok := n.X.(*ast.Ident); ok {
+				switch {
+				case daemonName != "" && x.Name == daemonName && daemonSymbols[n.Sel.Name]:
+					record("daemon."+n.Sel.Name, n.Sel.Pos())
+				case vmName != "" && x.Name == vmName && vmSymbols[n.Sel.Name]:
+					record("vm."+n.Sel.Name, n.Sel.Pos())
+				}
+			}
+			if jsmMethods[n.Sel.Name] || (ambiguousJSMMethods[n.Sel.Name] && jsmReceivers[receiverName(n.X)]) {
+				record("JetStreamManager."+n.Sel.Name, n.Sel.Pos())
+			}
+			// The selected name is a field or method, never a bare package symbol.
+			ast.Inspect(n.X, visit)
+			return false
+		case *ast.FuncDecl:
+			// A method declared with one of these names is an implementation,
+			// not a use; its body is still scanned.
+			if n.Recv != nil {
+				ast.Inspect(n.Recv, visit)
+			}
+			if n.Body != nil {
+				ast.Inspect(n.Body, visit)
+			}
+			if n.Type != nil {
+				ast.Inspect(n.Type, visit)
+			}
+			return false
+		case *ast.Field:
+			// Interface method and struct field names are declarations.
+			if n.Type != nil {
+				ast.Inspect(n.Type, visit)
+			}
+			if n.Tag != nil {
+				ast.Inspect(n.Tag, visit)
+			}
+			return false
+		case *ast.Ident:
+			if inDaemon && daemonSymbols[n.Name] {
+				record("daemon."+n.Name, n.Pos())
+			}
+			if inVM && vmSymbols[n.Name] {
+				record("vm."+n.Name, n.Pos())
+			}
+		}
+		return true
+	}
+	ast.Inspect(f, visit)
+}
+
+var jsmReceivers = set("jsManager", "jsm", "js")
+
+// receiverName is the last name in x: "js" for both js and a.js.
+func receiverName(x ast.Expr) string {
+	switch x := x.(type) {
+	case *ast.Ident:
+		return x.Name
+	case *ast.SelectorExpr:
+		return x.Sel.Name
+	}
+	return ""
+}
+
+// importName returns the name f refers to path by, or "" if f does not import it.
+func importName(f *ast.File, path, def string) string {
+	for _, imp := range f.Imports {
+		p, err := strconv.Unquote(imp.Path.Value)
+		if err != nil || p != path {
+			continue
+		}
+		if imp.Name != nil {
+			if imp.Name.Name == "_" || imp.Name.Name == "." {
+				return ""
+			}
+			return imp.Name.Name
+		}
+		return def
+	}
+	return ""
+}
+
+// ignoredByBuildTag reports a `//go:build ignore` file, which is a standalone
+// program rather than part of its directory's package.
+func ignoredByBuildTag(groups []*ast.CommentGroup, pkgPos token.Pos) bool {
+	for _, cg := range groups {
+		if cg.Pos() >= pkgPos {
+			break
+		}
+		for _, c := range cg.List {
+			if !constraint.IsGoBuild(c.Text) {
+				continue
+			}
+			expr, err := constraint.Parse(c.Text)
+			if err == nil && expr.String() == "ignore" {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func (s scan) sorted() []use {
+	out := make([]use, 0, len(s))
+	for u := range s {
+		out = append(out, u)
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].File != out[j].File {
+			return out[i].File < out[j].File
+		}
+		return out[i].Symbol < out[j].Symbol
+	})
+	return out
+}

architecture/layering/allowlist_test.go

@@ -0,0 +1,164 @@
+package layering
+
+// allowance is one recorded forbidden import, allowed until its debt clears.
+type allowance struct {
+	From, To string
+	Debt     string // subject of the migration record's debt entry or close-out row
+	Reason   string
+}
+
+// allowlist mirrors the dependency-rule debt and close-out table in
+// docs/PACKAGE_BOUNDARY_MIGRATION.md. It only shrinks: add an edge only with
+// recorded debt, and delete an entry as soon as its import is gone.
+var allowlist = []allowance{
+	{From: "accountteardown", To: "domains/ec2/awsapi/eip", Debt: "accountteardown (dependency)", Reason: "EC2 reapers call the awsapi action adapters; needs domain-owned cleanup capabilities"},
+	{From: "accountteardown", To: "domains/ec2/awsapi/igw", Debt: "accountteardown (dependency)", Reason: "EC2 reapers call the awsapi action adapters; needs domain-owned cleanup capabilities"},
+	{From: "accountteardown", To: "domains/ec2/awsapi/image", Debt: "accountteardown (dependency)", Reason: "EC2 reapers call the awsapi action adapters; needs domain-owned cleanup capabilities"},
+	{From: "accountteardown", To: "domains/ec2/awsapi/instance", Debt: "accountteardown (dependency)", Reason: "EC2 reapers call the awsapi action adapters; needs domain-owned cleanup capabilities"},
+	{From: "accountteardown", To: "domains/ec2/awsapi/key", Debt: "accountteardown (dependency)", Reason: "EC2 reapers call the awsapi action adapters; needs domain-owned cleanup capabilities"},
+	{From: "accountteardown", To: "domains/ec2/awsapi/launchtemplate", Debt: "accountteardown (dependency)", Reason: "EC2 reapers call the awsapi action adapters; needs domain-owned cleanup capabilities"},
+	{From: "accountteardown", To: "domains/ec2/awsapi/placementgroup", Debt: "accountteardown (dependency)", Reason: "EC2 reapers call the awsapi action adapters; needs domain-owned cleanup capabilities"},
+	{From: "accountteardown", To: "domains/ec2/awsapi/routetable", Debt: "accountteardown (dependency)", Reason: "EC2 reapers call the awsapi action adapters; needs domain-owned cleanup capabilities"},
+	{From: "accountteardown", To: "domains/ec2/awsapi/snapshot", Debt: "accountteardown (dependency)", Reason: "EC2 reapers call the awsapi action adapters; needs domain-owned cleanup capabilities"},
+	{From: "accountteardown", To: "domains/ec2/awsapi/volume", Debt: "accountteardown (dependency)", Reason: "EC2 reapers call the awsapi action adapters; needs domain-owned cleanup capabilities"},
+	{From: "accountteardown", To: "domains/ec2/awsapi/vpc", Debt: "accountteardown (dependency)", Reason: "EC2 reapers call the awsapi action adapters; needs domain-owned cleanup capabilities"},
+
+	{From: "agents/ecs/agent", To: "handlers/ecs", Debt: "agents/ecs/agent", Reason: "assignment/state wire types from the ECS implementation; needs a guest/controller contract"},
+
+	{From: "agents/eks/tokenwebhook", To: "handlers/eks", Debt: "agents/eks/tokenwebhook", Reason: "WebhookTokenReviewResult from the EKS implementation; needs an EKS contract or projection"},
+
+	{From: "agents/rds/agent", To: "handlers/rds", Debt: "agents/rds/agent (dependency, narrowed)", Reason: "command protocol, wire and record types; needs a guest/controller wire contract"},
+
+	{From: "cmd/aws-model-coverage", To: "domains/acm/awsapi", Debt: "cmd/aws-model-coverage", Reason: "reads declared ECR/ACM inventories; named exception, must not construct a registration"},
+	{From: "cmd/aws-model-coverage", To: "domains/ecr/awsapi", Debt: "cmd/aws-model-coverage", Reason: "reads declared ECR/ACM inventories; named exception, must not construct a registration"},
+
+	{From: "daemon", To: "domains/ec2/awsapi/instance", Debt: "Instance adapter consumers outside EC2", Reason: "daemon/eks_cp_control.go and rds_deps.go call the instance adapter; needs an EC2 capability"},
+
+	{From: "domains/acm", To: "handlers/iam", Debt: "ACM: the IAM AES-GCM helper import (ACM relocation residual)", Reason: "IAM AES-GCM helpers; needs a shared crypto boundary"},
+
+	{From: "domains/admission/quota", To: "domains/ec2/awsapi/eip", Debt: "domains/admission/quota (dependency, moved from handlers/quota unchanged)", Reason: "describe adapter used as a counter; needs a reader capability"},
+	{From: "domains/admission/quota", To: "domains/ec2/awsapi/instance", Debt: "domains/admission/quota (dependency, moved from handlers/quota unchanged)", Reason: "vcpu.go counts instances through the instance adapter; needs an EC2 reader capability"},
+	{From: "domains/admission/quota", To: "domains/ec2/awsapi/volume", Debt: "domains/admission/quota (dependency, moved from handlers/quota unchanged)", Reason: "describe adapter used as a counter; needs a reader capability"},
+	{From: "domains/admission/quota", To: "domains/ec2/awsapi/vpc", Debt: "domains/admission/quota (dependency, moved from handlers/quota unchanged)", Reason: "describe adapter used as a counter; needs a reader capability"},
+	{From: "domains/admission/quota", To: "domains/ec2/instancetypes", Debt: "domains/admission/quota → domains/ec2/instancetypes", Reason: "DefaultVCPUs sizing; needs a consumer-owned capability or EC2 projection"},
+	{From: "domains/admission/quota", To: "gateway/elbv2", Debt: "domains/admission/quota (dependency, moved from handlers/quota unchanged)", Reason: "live ELBv2 counter; needs a reader capability"},
+	{From: "domains/admission/quota", To: "handlers/rds", Debt: "domains/admission/quota (dependency, moved from handlers/quota unchanged)", Reason: "live RDS counter; needs a reader capability"},
+	{From: "domains/admission/quota", To: "runtime/compute/vm", Debt: "domains/admission/quota (dependency, moved from handlers/quota unchanged)", Reason: "instance-record vCPU sweep; needs a reader capability"},
+
+	{From: "domains/dns", To: "domains/network/reconcile", Debt: "domains/dns", Reason: "takes the reconcile lock from network's implementation"},
+	{From: "domains/dns", To: "runtime/compute/vm", Debt: "domains/dns", Reason: "domain-to-runtime import of VM state"},
+
+	{From: "domains/ec2/awsapi/instance", To: "handlers/iam", Debt: "domains/ec2/awsapi/instance (dependency)", Reason: "IAM edge needs an IAM capability"},
+	{From: "domains/ec2/awsapi/instance", To: "runtime/compute/cache", Debt: "domains/ec2/awsapi/instance (dependency)", Reason: "node liveness and VM state; needs an EC2-owned projection"},
+	{From: "domains/ec2/awsapi/instance", To: "runtime/compute/vm", Debt: "domains/ec2/awsapi/instance (dependency)", Reason: "node liveness and VM state; needs an EC2-owned projection"},
+
+	{From: "domains/ec2/awsapi/spotinstance", To: "domains/admission/quota", Debt: "domains/ec2/awsapi/spotinstance (dependency)", Reason: "RequestSpotInstances.go uses IAMService and quota.Service"},
+	{From: "domains/ec2/awsapi/spotinstance", To: "handlers/iam", Debt: "domains/ec2/awsapi/spotinstance (dependency)", Reason: "RequestSpotInstances.go uses IAMService and quota.Service"},
+
+	{From: "domains/ec2/eip", To: "domains/network/topology", Debt: "EC2 → network implementation", Reason: "EC2 reads network implementation; clears with the EC2-owned projection"},
+
+	{From: "domains/ec2/guestmetadata", To: "domains/dns", Debt: "Guest metadata: the cross-domain and runtime imports above", Reason: "guest-metadata relocation residual; needs capabilities, projections or contracts"},
+	{From: "domains/ec2/guestmetadata", To: "handlers/iam", Debt: "Guest metadata: the cross-domain and runtime imports above", Reason: "guest-metadata relocation residual; needs capabilities, projections or contracts"},
+	{From: "domains/ec2/guestmetadata", To: "handlers/sts", Debt: "Guest metadata: the cross-domain and runtime imports above", Reason: "guest-metadata relocation residual; needs capabilities, projections or contracts"},
+	{From: "domains/ec2/guestmetadata", To: "runtime/compute/vm", Debt: "Guest metadata: the cross-domain and runtime imports above", Reason: "guest-metadata relocation residual; needs capabilities, projections or contracts"},
+
+	{From: "domains/ec2/instance", To: "domains/dns", Debt: "domains/ec2/instance", Reason: "cross-domain implementation import of DNS"},
+	{From: "domains/ec2/instance", To: "domains/network/topology", Debt: "EC2 → network implementation", Reason: "EC2 reads network implementation; clears with the EC2-owned projection"},
+	{From: "domains/ec2/instance", To: "runtime/compute/gpu", Debt: "domains/ec2/instance", Reason: "VM/GPU runtime state read directly; needs a domain-owned projection"},
+	{From: "domains/ec2/instance", To: "runtime/compute/vm", Debt: "domains/ec2/instance", Reason: "VM/GPU runtime state read directly; needs a domain-owned projection"},
+	{From: "domains/ec2/instance/state", To: "daemon", Debt: "domains/ec2/instance/state (dependency, IMDS readers)", Reason: "wraps the daemon's local-file reader and JetStreamManager bucket open unchanged for vpcd's IMDS lookup"},
+	{From: "domains/ec2/instance/state", To: "runtime/compute/vm", Debt: "domains/ec2/instance/state (dependency)", Reason: "the vpcd IMDS local reader returns vm.VM"},
+
+	{From: "domains/ec2/volume", To: "runtime/compute/vm", Debt: "Domain → runtime", Reason: "VM runtime state read directly; needs a domain-owned projection"},
+
+	{From: "domains/ec2/vpc", To: "domains/network/external", Debt: "EC2 → network implementation", Reason: "EC2 reads network implementation; clears with the EC2-owned projection"},
+	{From: "domains/ec2/vpc", To: "domains/network/external/dhcp", Debt: "EC2 → network implementation", Reason: "EC2 reads network implementation; clears with the EC2-owned projection"},
+	{From: "domains/ec2/vpc", To: "domains/network/identifiers", Debt: "EC2 → network implementation", Reason: "EC2 reads network implementation; clears with the EC2-owned projection"},
+	{From: "domains/ec2/vpc", To: "domains/network/topology", Debt: "EC2 → network implementation", Reason: "EC2 reads network implementation; clears with the EC2-owned projection"},
+
+	{From: "domains/ecr/auth", To: "handlers/iam", Debt: "Cross-domain", Reason: "IAM implementation import; needs an IAM capability"},
+
+	{From: "domains/network/host", To: "runtime/compute/vm", Debt: "domains/network", Reason: "domain-to-runtime import"},
+	{From: "domains/network/host", To: "runtime/host/command", Debt: "domains/network", Reason: "domain-to-runtime import"},
+
+	{From: "domains/network/reconcile", To: "domains/ec2/eip", Debt: "domains/network", Reason: "reconcile reads EC2 private records; clears with the EC2-owned projection"},
+	{From: "domains/network/reconcile", To: "domains/ec2/igw", Debt: "domains/network", Reason: "reconcile reads EC2 private records; clears with the EC2-owned projection"},
+	{From: "domains/network/reconcile", To: "domains/ec2/natgw", Debt: "domains/network", Reason: "reconcile reads EC2 private records; clears with the EC2-owned projection"},
+	{From: "domains/network/reconcile", To: "domains/ec2/routetable", Debt: "domains/network", Reason: "reconcile reads EC2 private records; clears with the EC2-owned projection"},
+	{From: "domains/network/reconcile", To: "domains/ec2/vpc", Debt: "domains/network", Reason: "reconcile reads EC2 private records; clears with the EC2-owned projection"},
+	{From: "domains/network/reconcile", To: "runtime/compute/vm", Debt: "domains/network", Reason: "domain-to-runtime import"},
+
+	{From: "domains/ochre", To: "domains/ec2/systeminstance", Debt: "Cross-domain", Reason: "consumes another domain's implementation rather than a capability"},
+	{From: "domains/ochre", To: "domains/network/systemvpc", Debt: "Cross-domain", Reason: "consumes another domain's implementation rather than a capability"},
+	{From: "domains/ochre", To: "gateway/bedrock", Debt: "gateway/bedrock", Reason: "Ochre domain core still lives in gateway/bedrock; needs the recorded split"},
+	{From: "domains/ochre", To: "runtime/compute/gpu", Debt: "Domain → runtime", Reason: "GPU runtime state read directly; needs a domain-owned projection"},
+
+	{From: "domains/ochre/vector", To: "handlers/iam", Debt: "Cross-domain", Reason: "consumes another domain's implementation rather than a capability"},
+
+	{From: "gateway", To: "domains/ec2/awsapi", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/account", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/capacityreservation", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/eigw", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/eip", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/idem", Debt: "gateway/ec2.go (registration; ec2_idempotency.go)", Reason: "dispatch-time idempotency wrapper; moves with the EC2 dispatch map"},
+	{From: "gateway", To: "domains/ec2/awsapi/igw", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/image", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/instance", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/key", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/launchtemplate", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/natgw", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/placementgroup", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/routetable", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/snapshot", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/spotinstance", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/tags", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/volume", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/vpc", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+	{From: "gateway", To: "domains/ec2/awsapi/zone", Debt: "gateway/ec2.go (registration)", Reason: "EC2 dispatch map stays in gateway until the ingress registration seam"},
+
+	{From: "gateway/bedrock", To: "handlers/iam", Debt: "IAM implementation consumers in STS, Ochre and ELBv2", Reason: "secret encrypt/decrypt helpers; needs a shared crypto boundary"},
+
+	{From: "gateway/rds", To: "domains/ec2/awsapi/instance", Debt: "Instance adapter consumers outside EC2", Reason: "enginecatalog.go calls the instance adapter; needs an EC2 capability"},
+
+	{From: "gateway/sts", To: "handlers/iam", Debt: "IAM implementation consumers in STS, Ochre and ELBv2", Reason: "GetCallerIdentity takes IAMService; needs an IAM capability"},
+
+	{From: "handlers/ecs", To: "domains/ec2/ebs/metadata", Debt: "close-out: handlers/ecs (ADR-0004 blocked-dependency list; inventory-ecs boundary imports)", Reason: "legacy ECS calls another domain's implementation as an internal API"},
+	{From: "handlers/ecs", To: "domains/ec2/eip", Debt: "close-out: handlers/ecs (ADR-0004 blocked-dependency list; inventory-ecs boundary imports)", Reason: "legacy ECS calls another domain's implementation as an internal API"},
+	{From: "handlers/ecs", To: "domains/ec2/instancetypes", Debt: "close-out: handlers/ecs (ADR-0004 blocked-dependency list; inventory-ecs boundary imports)", Reason: "legacy ECS calls another domain's implementation as an internal API"},
+	{From: "handlers/ecs", To: "handlers/elbv2", Debt: "close-out: handlers/ecs (ADR-0004 blocked-dependency list; inventory-ecs boundary imports)", Reason: "legacy ECS calls another domain's implementation as an internal API"},
+	{From: "handlers/ecs", To: "handlers/iam", Debt: "close-out: handlers/ecs (ADR-0004 blocked-dependency list; inventory-ecs boundary imports)", Reason: "legacy ECS calls another domain's implementation as an internal API"},
+
+	{From: "handlers/eks", To: "domains/dns", Debt: "close-out: handlers/eks (ADR-0004 blocked-dependency list; inventory-eks boundary imports)", Reason: "legacy EKS calls another domain's or runtime implementation directly"},
+	{From: "handlers/eks", To: "domains/ec2/ebs/metadata", Debt: "close-out: handlers/eks (ADR-0004 blocked-dependency list; inventory-eks boundary imports)", Reason: "legacy EKS calls another domain's or runtime implementation directly"},
+	{From: "handlers/eks", To: "domains/ec2/instancetypes", Debt: "close-out: handlers/eks (ADR-0004 blocked-dependency list; inventory-eks boundary imports)", Reason: "legacy EKS calls another domain's or runtime implementation directly"},
+	{From: "handlers/eks", To: "domains/ec2/placementgroup", Debt: "close-out: handlers/eks (ADR-0004 blocked-dependency list; inventory-eks boundary imports)", Reason: "legacy EKS calls another domain's or runtime implementation directly"},
+	{From: "handlers/eks", To: "domains/ec2/systeminstance", Debt: "close-out: handlers/eks (ADR-0004 blocked-dependency list; inventory-eks boundary imports)", Reason: "legacy EKS calls another domain's or runtime implementation directly"},
+	{From: "handlers/eks", To: "domains/network/systemvpc", Debt: "close-out: handlers/eks (ADR-0004 blocked-dependency list; inventory-eks boundary imports)", Reason: "legacy EKS calls another domain's or runtime implementation directly"},
+	{From: "handlers/eks", To: "handlers/iam", Debt: "close-out: handlers/eks (ADR-0004 blocked-dependency list; inventory-eks boundary imports)", Reason: "legacy EKS calls another domain's or runtime implementation directly"},
+	{From: "handlers/eks", To: "runtime/compute/vm", Debt: "close-out: handlers/eks (ADR-0004 blocked-dependency list; inventory-eks boundary imports)", Reason: "legacy EKS calls another domain's or runtime implementation directly"},
+
+	{From: "handlers/elbv2", To: "domains/acm", Debt: "handlers/elbv2 (cross-domain)", Reason: "legacy ELBv2 cross-domain import; clears when ELBv2 is extracted behind consumer-owned capabilities"},
+	{From: "handlers/elbv2", To: "domains/dns", Debt: "handlers/elbv2 (cross-domain)", Reason: "legacy ELBv2 cross-domain import; clears when ELBv2 is extracted behind consumer-owned capabilities"},
+	{From: "handlers/elbv2", To: "domains/ec2/systeminstance", Debt: "handlers/elbv2 (cross-domain)", Reason: "legacy ELBv2 cross-domain import; clears when ELBv2 is extracted behind consumer-owned capabilities"},
+	{From: "handlers/elbv2", To: "domains/ec2/vpc", Debt: "handlers/elbv2 (cross-domain)", Reason: "legacy ELBv2 cross-domain import; clears when ELBv2 is extracted behind consumer-owned capabilities"},
+	{From: "handlers/elbv2", To: "domains/network/topology", Debt: "handlers/elbv2 (cross-domain)", Reason: "legacy ELBv2 cross-domain import; clears when ELBv2 is extracted behind consumer-owned capabilities"},
+	{From: "handlers/elbv2", To: "handlers/iam", Debt: "IAM implementation consumers in STS, Ochre and ELBv2", Reason: "system-instance role ensurer; needs an IAM capability"},
+	{From: "handlers/elbv2", To: "lbagent", Debt: "handlers/elbv2/{agent_types,haproxy,health_checker,nginx}.go import lbagent", Reason: "health-report and cert/PID-path vocabulary; needs a guest/controller contract"},
+
+	{From: "handlers/rds", To: "domains/dns", Debt: "close-out: handlers/rds (ADR-0004 blocked-dependency list; inventory-rds boundary imports)", Reason: "legacy RDS calls another domain's or runtime implementation directly"},
+	{From: "handlers/rds", To: "domains/ec2/instance", Debt: "close-out: handlers/rds (ADR-0004 blocked-dependency list; inventory-rds boundary imports)", Reason: "legacy RDS calls another domain's or runtime implementation directly"},
+	{From: "handlers/rds", To: "domains/ec2/instancetypes", Debt: "close-out: handlers/rds (ADR-0004 blocked-dependency list; inventory-rds boundary imports)", Reason: "legacy RDS calls another domain's or runtime implementation directly"},
+	{From: "handlers/rds", To: "domains/ec2/systeminstance", Debt: "close-out: handlers/rds (ADR-0004 blocked-dependency list; inventory-rds boundary imports)", Reason: "legacy RDS calls another domain's or runtime implementation directly"},
+	{From: "handlers/rds", To: "domains/network/systemvpc", Debt: "close-out: handlers/rds (ADR-0004 blocked-dependency list; inventory-rds boundary imports)", Reason: "legacy RDS calls another domain's or runtime implementation directly"},
+	{From: "handlers/rds", To: "handlers/iam", Debt: "close-out: handlers/rds (ADR-0004 blocked-dependency list; inventory-rds boundary imports)", Reason: "legacy RDS calls another domain's or runtime implementation directly"},
+	{From: "handlers/rds", To: "runtime/compute/vm", Debt: "close-out: handlers/rds (ADR-0004 blocked-dependency list; inventory-rds boundary imports)", Reason: "legacy RDS calls another domain's or runtime implementation directly"},
+
+	{From: "handlers/sts", To: "handlers/iam", Debt: "IAM implementation consumers in STS, Ochre and ELBv2", Reason: "STS reads IAM service, trust-policy and OIDC-provider state; needs an IAM capability"},
+
+	{From: "operator/cli", To: "accountteardown", Debt: "operator/cli (dependency)", Reason: "command tree imports implementations; needs public capabilities"},
+	{From: "operator/cli", To: "daemon", Debt: "operator/cli (dependency)", Reason: "command tree imports implementations; needs public capabilities"},
+	{From: "operator/cli", To: "gateway", Debt: "operator/cli (dependency)", Reason: "command tree imports implementations; needs public capabilities"},
+	{From: "operator/cli", To: "gateway/bedrock", Debt: "operator/cli (dependency)", Reason: "command tree imports implementations; needs public capabilities"},
+	{From: "operator/cli", To: "handlers/eks", Debt: "operator/cli (dependency)", Reason: "command tree imports implementations; needs public capabilities"},
+	{From: "operator/cli", To: "handlers/iam", Debt: "operator/cli (dependency)", Reason: "command tree imports implementations; needs public capabilities"},
+}

architecture/layering/graph_test.go

@@ -0,0 +1,163 @@
+// Package layering enforces ADR-0001's package-boundary dependency rules over
+// the module's production import graph, ratcheted by a recorded-debt allowlist.
+package layering
+
+import (
+	"errors"
+	"fmt"
+	"go/ast"
+	"go/build/constraint"
+	"go/parser"
+	"go/token"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"runtime"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+const modulePath = "github.com/mulgadc/spinifex"
+
+// edge is one package-to-package import, both sides named as in the allowlist:
+// application packages relative to spinifex/, module-root ones (cmd/,
+// contracts/, internal/) relative to the module root.
+type edge struct {
+	From, To string
+}
+
+func (e edge) String() string { return e.From + " -> " + e.To }
+
+// graph is the production import graph restricted to this module.
+type graph struct {
+	// pkgs maps a package name to its module-relative directory.
+	pkgs map[string]string
+	// imports records the first file:line at which each edge appears.
+	imports map[edge]string
+}
+
+func newGraph() *graph {
+	return &graph{pkgs: map[string]string{}, imports: map[edge]string{}}
+}
+
+// shortName drops the application-root prefix so names read like the ADR and
+// the migration record; classify rejects app-root dirs that would collide.
+func shortName(full string) string {
+	if rest, ok := strings.CutPrefix(full, "spinifex/"); ok {
+		return rest
+	}
+	return full
+}
+
+func moduleRoot() (string, error) {
+	_, file, _, ok := runtime.Caller(0)
+	if !ok {
+		return "", errors.New("cannot locate test source")
+	}
+	// architecture/layering/graph_test.go -> module root.
+	return filepath.Abs(filepath.Join(filepath.Dir(file), "..", ".."))
+}
+
+// excludedTopDirs hold no production code: tests/ is test-only, docs/ only
+// embeds documentation and architecture/ is repository governance tooling.
+var excludedTopDirs = map[string]bool{"tests": true, "docs": true, "architecture": true}
+
+// loadGraph parses the imports of every non-test Go file under root, so it
+// sees every build-tag variant and needs no Go toolchain or workspace.
+func loadGraph(root string) (*graph, error) {
+	g := newGraph()
+	fset := token.NewFileSet()
+	err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		rel, err := filepath.Rel(root, path)
+		if err != nil {
+			return err
+		}
+		rel = filepath.ToSlash(rel)
+		if d.IsDir() {
+			if rel == "." {
+				return nil
+			}
+			name := d.Name()
+			if strings.HasPrefix(name, ".") || strings.HasPrefix(name, "_") ||
+				name == "testdata" || name == "vendor" || name == "node_modules" || excludedTopDirs[rel] {
+				return filepath.SkipDir
+			}
+			if _, err := os.Stat(filepath.Join(path, "go.mod")); err == nil {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+			return nil
+		}
+		f, err := parser.ParseFile(fset, path, nil, parser.ImportsOnly|parser.ParseComments)
+		if err != nil {
+			return err
+		}
+		if ignoredByBuildTag(f.Comments, f.Package) {
+			return nil
+		}
+		dir := filepath.ToSlash(filepath.Dir(rel))
+		if dir == "." {
+			dir = ""
+		}
+		from := shortName(dir)
+		g.pkgs[from] = dir
+		for _, imp := range f.Imports {
+			p, err := strconv.Unquote(imp.Path.Value)
+			if err != nil {
+				return err
+			}
+			target, ok := strings.CutPrefix(p, modulePath+"/")
+			if !ok {
+				continue
+			}
+			e := edge{From: from, To: shortName(target)}
+			if _, seen := g.imports[e]; !seen {
+				pos := fset.Position(imp.Pos())
+				g.imports[e] = fmt.Sprintf("%s:%d", rel, pos.Line)
+			}
+		}
+		return nil
+	})
+	return g, err
+}
+
+// ignoredByBuildTag reports a `//go:build ignore` file, which is a standalone
+// program (a generator) rather than part of its directory's package.
+func ignoredByBuildTag(groups []*ast.CommentGroup, pkgPos token.Pos) bool {
+	for _, cg := range groups {
+		if cg.Pos() >= pkgPos {
+			break
+		}
+		for _, c := range cg.List {
+			if !constraint.IsGoBuild(c.Text) {
+				continue
+			}
+			expr, err := constraint.Parse(c.Text)
+			if err == nil && expr.String() == "ignore" {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// sortedEdges returns the graph's edges in a stable order.
+func (g *graph) sortedEdges() []edge {
+	out := make([]edge, 0, len(g.imports))
+	for e := range g.imports {
+		out = append(out, e)
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].From != out[j].From {
+			return out[i].From < out[j].From
+		}
+		return out[i].To < out[j].To
+	})
+	return out
+}

architecture/layering/layering_test.go

@@ -0,0 +1,193 @@
+package layering
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+	"testing"
+)
+
+type violation struct {
+	rule string
+	edge edge
+	pos  string
+}
+
+type report struct {
+	unmapped   []string
+	violations []violation // every rule hit, allowlisted or not
+	unrecorded []violation // hits whose edge has no allowlist entry
+	stale      []allowance // entries whose edge no rule rejects any more
+	malformed  []string
+}
+
+// check classifies g, applies every rule and compares the result with allow.
+func check(g *graph, allow []allowance) report {
+	var rep report
+	classes := map[string]class{}
+	for name, dir := range g.pkgs {
+		c, ok := classify(dir)
+		if !ok || c.layer == layerTests {
+			rep.unmapped = append(rep.unmapped, fmt.Sprintf("%s (directory %s)", name, dir))
+			continue
+		}
+		classes[name] = c
+	}
+
+	allowed := map[edge]bool{}
+	for _, a := range allow {
+		e := edge{From: a.From, To: a.To}
+		switch {
+		case allowed[e]:
+			rep.malformed = append(rep.malformed, "duplicate entry "+e.String())
+		case a.Debt == "" || a.Reason == "":
+			rep.malformed = append(rep.malformed, "entry "+e.String()+" needs both Debt and Reason")
+		}
+		allowed[e] = true
+	}
+
+	hit := map[edge]bool{}
+	for _, e := range g.sortedEdges() {
+		from, ok := classes[e.From]
+		if !ok {
+			continue
+		}
+		to, ok := classify(fullPath(e.To))
+		if !ok {
+			rep.unmapped = append(rep.unmapped, fmt.Sprintf("%s (imported by %s at %s)", e.To, e.From, g.imports[e]))
+			continue
+		}
+		for _, r := range rules {
+			if !r.subject(from, e.From) || !r.forbids(from, to, e.From) {
+				continue
+			}
+			v := violation{rule: r.id, edge: e, pos: g.imports[e]}
+			rep.violations = append(rep.violations, v)
+			hit[e] = true
+			if !allowed[e] {
+				rep.unrecorded = append(rep.unrecorded, v)
+			}
+		}
+	}
+	for _, a := range allow {
+		if !hit[edge{From: a.From, To: a.To}] {
+			rep.stale = append(rep.stale, a)
+		}
+	}
+	sort.Strings(rep.unmapped)
+	return rep
+}
+
+func ruleByID(id string) rule {
+	for _, r := range rules {
+		if r.id == id {
+			return r
+		}
+	}
+	panic("unknown rule " + id)
+}
+
+// TestADR0001_Layering is the blocking ratchet over the real import graph.
+func TestADR0001_Layering(t *testing.T) {
+	root, err := moduleRoot()
+	if err != nil {
+		t.Fatal(err)
+	}
+	g, err := loadGraph(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Guards against a walk that silently finds nothing and passes vacuously.
+	if len(g.pkgs) < 100 || len(g.imports) < 500 {
+		t.Fatalf("scanned %d packages and %d module imports under %s; the walk has lost the tree and every rule would pass vacuously",
+			len(g.pkgs), len(g.imports), root)
+	}
+	rep := check(g, allowlist)
+
+	t.Run("Classification_EveryPackageMapped", func(t *testing.T) {
+		for _, u := range rep.unmapped {
+			t.Errorf("ADR-0001 current-to-target map: package %s has no layer; place it under an ADR-0001 home or classify it deliberately in layers_test.go", u)
+		}
+	})
+
+	for _, r := range rules {
+		t.Run(r.id, func(t *testing.T) {
+			subjects := 0
+			for name, dir := range g.pkgs {
+				if c, ok := classify(dir); ok && r.subject(c, name) {
+					subjects++
+				}
+			}
+			if subjects == 0 {
+				t.Fatalf("no scanned package is governed by %s; the rule would pass vacuously", r.id)
+			}
+			var snippets []string
+			for _, v := range rep.unrecorded {
+				if v.rule != r.id {
+					continue
+				}
+				t.Errorf("ADR-0001 %s: %s imports %s (%s); %s",
+					r.clause, v.edge.From, v.edge.To, v.pos, r.hint)
+				snippets = append(snippets, fmt.Sprintf("{From: %q, To: %q, Debt: \"<migration-record debt subject>\", Reason: \"<why>\"},", v.edge.From, v.edge.To))
+			}
+			if len(snippets) > 0 {
+				t.Logf("fix the import; only debt already recorded in docs/PACKAGE_BOUNDARY_MIGRATION.md may be allow-listed:\n%s",
+					strings.Join(snippets, "\n"))
+			}
+		})
+	}
+
+	t.Run("Allowlist_NoStaleEntries", func(t *testing.T) {
+		for _, a := range rep.stale {
+			t.Errorf("allowlist entry %s -> %s (%s) no longer matches a forbidden import; the debt is paid, so delete the entry from allowlist_test.go",
+				a.From, a.To, a.Debt)
+		}
+	})
+
+	t.Run("Allowlist_WellFormed", func(t *testing.T) {
+		for _, m := range rep.malformed {
+			t.Errorf("allowlist_test.go: %s", m)
+		}
+		t.Logf("%d allow-listed edges", len(allowlist))
+	})
+}
+
+// TestADR0001_LayeringCheckerDetectsFaults injects a forbidden edge, a stale
+// allowlist entry and an unmapped package into a synthetic graph.
+func TestADR0001_LayeringCheckerDetectsFaults(t *testing.T) {
+	g := newGraph()
+	for _, dir := range []string{
+		"spinifex/foundation/widget", "spinifex/domains/alpha/thing",
+		"spinifex/domains/beta/store", "spinifex/misc",
+	} {
+		g.pkgs[shortName(dir)] = dir
+	}
+	forbidden := edge{From: "foundation/widget", To: "domains/alpha/thing"}
+	g.imports[forbidden] = "spinifex/foundation/widget/w.go:7"
+	allowedEdge := edge{From: "domains/alpha/thing", To: "domains/beta/store"}
+	g.imports[allowedEdge] = "spinifex/domains/alpha/thing/t.go:9"
+
+	staleEntry := allowance{From: "domains/beta/store", To: "domains/alpha/thing", Debt: "synthetic", Reason: "stale"}
+	rep := check(g, []allowance{
+		{From: allowedEdge.From, To: allowedEdge.To, Debt: "synthetic", Reason: "recorded"},
+		staleEntry,
+	})
+
+	if len(rep.unrecorded) != 1 || rep.unrecorded[0].edge != forbidden ||
+		rep.unrecorded[0].rule != ruleByID("R1_FoundationImportsOnlyFoundation").id {
+		t.Errorf("want only %s reported under R1, got %+v", forbidden, rep.unrecorded)
+	}
+	if len(rep.stale) != 1 || rep.stale[0] != staleEntry {
+		t.Errorf("want stale entry %+v, got %+v", staleEntry, rep.stale)
+	}
+	if len(rep.unmapped) != 1 || !strings.HasPrefix(rep.unmapped[0], "misc ") {
+		t.Errorf("want unmapped package misc, got %v", rep.unmapped)
+	}
+	var allowedHit bool
+	for _, v := range rep.violations {
+		allowedHit = allowedHit || v.edge == allowedEdge
+	}
+	if !allowedHit {
+		t.Errorf("allow-listed cross-domain edge %s was not detected by R3, so the allowlist entry would read as stale", allowedEdge)
+	}
+}

architecture/layering/layers_test.go

@@ -0,0 +1,164 @@
+package layering
+
+import (
+	"slices"
+	"strings"
+)
+
+type layer string
+
+const (
+	layerFoundation layer = "foundation"
+	layerContracts  layer = "contracts"
+	layerDomain     layer = "domains"
+	layerIngress    layer = "ingress"
+	layerRuntime    layer = "runtime"
+	layerOperator   layer = "operator"
+	layerAgents     layer = "agents"
+	layerProviders  layer = "providers"
+	layerBootstrap  layer = "bootstrap"
+	layerCmd        layer = "cmd"
+	layerInternal   layer = "internal"
+	layerTestkit    layer = "testkit"
+	layerLegacy     layer = "legacy"
+	// layerTests is valid only as an import target; tests/ is never scanned.
+	layerTests layer = "tests"
+)
+
+// domainKind distinguishes the parts of a domain the rules treat differently.
+type domainKind int
+
+const (
+	notDomain     domainKind = iota
+	domainImpl               // domains/<d>/... resource implementation
+	domainAWSAPI             // domains/<d>/awsapi/... AWS action adapters
+	domainProj               // domains/<d>/projection/... authorised view
+	legacyImpl               // handlers/<d>/... legacy domain implementation
+	legacyAdapter            // gateway/<d>/... legacy AWS action adapters
+)
+
+type class struct {
+	layer  layer
+	legacy string // legacy root name when layer is layerLegacy
+	domain string // owning domain for domain-shaped and agent packages
+	kind   domainKind
+}
+
+func (c class) domainShaped() bool { return c.kind != notDomain }
+
+// isLegacy reports whether c sits under one of the named legacy roots.
+func (c class) isLegacy(roots ...string) bool {
+	if c.layer != layerLegacy {
+		return false
+	}
+	if len(roots) == 0 {
+		return true
+	}
+	return slices.Contains(roots, c.legacy)
+}
+
+// legacyRoots are pre-ADR-0001 application roots still standing.
+var legacyRoots = map[string]bool{
+	"handlers": true, "gateway": true, "daemon": true,
+	"accountteardown": true, "lbagent": true,
+}
+
+// gatewayDomains names the domain each gateway/<service> adapter belongs to;
+// Bedrock is the AWS surface of the Ochre domain.
+var gatewayDomains = map[string]string{
+	"bedrock": "ochre", "ecs": "ecs", "eks": "eks", "elbv2": "elbv2", "iam": "iam",
+	"rds": "rds", "sts": "sts",
+}
+
+// runtimeLegacy and operatorLegacy are the legacy roots whose ADR-0001 target
+// is runtime/ and operator/ respectively.
+var (
+	runtimeLegacy  = []string{"daemon"}
+	operatorLegacy = []string{"accountteardown"}
+)
+
+// classify maps a module-relative package directory to its layer. ok is false
+// for a package that has no deliberate classification.
+func classify(full string) (class, bool) {
+	parts := strings.Split(full, "/")
+	switch parts[0] {
+	case "cmd":
+		return class{layer: layerCmd}, len(parts) >= 2
+	case "contracts":
+		return class{layer: layerContracts}, len(parts) >= 2
+	case "internal":
+		if len(parts) < 2 {
+			return class{}, false
+		}
+		if parts[1] == "testkit" || parts[1] == "tooling" {
+			return class{layer: layerTestkit}, true
+		}
+		return class{layer: layerInternal}, true
+	case "tests":
+		return class{layer: layerTests}, true
+	case "spinifex":
+		return classifyApp(parts[1:])
+	}
+	return class{}, false
+}
+
+func classifyApp(app []string) (class, bool) {
+	if len(app) == 0 {
+		return class{}, false
+	}
+	switch app[0] {
+	case "foundation":
+		return class{layer: layerFoundation}, true
+	case "ingress":
+		return class{layer: layerIngress}, true
+	case "runtime":
+		return class{layer: layerRuntime}, true
+	case "operator":
+		return class{layer: layerOperator}, true
+	case "providers":
+		return class{layer: layerProviders}, true
+	case "bootstrap":
+		return class{layer: layerBootstrap}, true
+	case "agents":
+		c := class{layer: layerAgents}
+		if len(app) >= 2 {
+			c.domain = app[1]
+		}
+		return c, true
+	case "domains":
+		if len(app) < 2 {
+			return class{}, false
+		}
+		c := class{layer: layerDomain, domain: app[1], kind: domainImpl}
+		if len(app) >= 3 {
+			switch app[2] {
+			case "awsapi":
+				c.kind = domainAWSAPI
+			case "projection":
+				c.kind = domainProj
+			}
+		}
+		return c, true
+	}
+	if !legacyRoots[app[0]] {
+		return class{}, false
+	}
+	c := class{layer: layerLegacy, legacy: app[0]}
+	switch {
+	case app[0] == "handlers" && len(app) >= 2:
+		c.domain, c.kind = app[1], legacyImpl
+	case app[0] == "gateway" && len(app) >= 2 && gatewayDomains[app[1]] != "":
+		c.domain, c.kind = gatewayDomains[app[1]], legacyAdapter
+	}
+	return c, true
+}
+
+// fullPath reverses shortName for classification.
+func fullPath(name string) string {
+	top, _, _ := strings.Cut(name, "/")
+	switch top {
+	case "cmd", "contracts", "internal", "tests", "docs":
+		return name
+	}
+	return "spinifex/" + name
+}

architecture/layering/legacy_test.go

@@ -0,0 +1,81 @@
+package layering
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// frozenLegacyPackages is every production package still under a legacy root.
+// It only shrinks: a new entry is a new legacy package, a missing one is a
+// completed move whose line must be deleted.
+var frozenLegacyPackages = []string{
+	"accountteardown",
+	"daemon",
+	"gateway",
+	"gateway/bedrock",
+	"gateway/ecs",
+	"gateway/eks",
+	"gateway/elbv2",
+	"gateway/iam",
+	"gateway/rds",
+	"gateway/spx",
+	"gateway/sts",
+	"handlers/ecs",
+	"handlers/eks",
+	"handlers/elbv2",
+	"handlers/iam",
+	"handlers/iam/mock",
+	"handlers/rds",
+	"handlers/sts",
+	"lbagent",
+}
+
+// retiredLegacyRoots were legacy roots whose every package has moved to its
+// ADR-0001 target; recreating one would reopen a closed migration row.
+var retiredLegacyRoots = []string{"admin", "services", "utils", "vpcd"}
+
+// TestADR0001_LegacyRootsFrozen: the current-to-target map gives every legacy
+// root a destination, so none may gain a package and no retired root may return.
+func TestADR0001_LegacyRootsFrozen(t *testing.T) {
+	root, err := moduleRoot()
+	if err != nil {
+		t.Fatal(err)
+	}
+	g, err := loadGraph(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	present := map[string]bool{}
+	for name, dir := range g.pkgs {
+		if c, ok := classify(dir); ok && c.layer == layerLegacy {
+			present[name] = true
+		}
+	}
+	if len(present) == 0 {
+		t.Fatal("found no legacy packages; the freeze would pass vacuously")
+	}
+	frozen := map[string]bool{}
+	for _, p := range frozenLegacyPackages {
+		frozen[p] = true
+		if !present[p] {
+			t.Errorf("legacy package %s no longer exists; delete it from frozenLegacyPackages", p)
+		}
+	}
+	for p := range present {
+		if !frozen[p] {
+			t.Errorf("ADR-0001 current-to-target map: %s is a new package under a legacy root; create it at its ADR-0001 target home instead", p)
+		}
+	}
+
+	for _, r := range retiredLegacyRoots {
+		entries, err := os.ReadDir(filepath.Join(root, "spinifex", r))
+		if err != nil && !os.IsNotExist(err) {
+			t.Fatal(err)
+		}
+		if len(entries) > 0 {
+			t.Errorf("ADR-0001 current-to-target map: spinifex/%s is a retired legacy root; give the code its target home instead", r)
+		}
+	}
+}

architecture/layering/rules_test.go

@@ -0,0 +1,170 @@
+package layering
+
+import "slices"
+
+// rule is one ADR-0001 dependency rule over a classified import edge.
+type rule struct {
+	id     string // subtest name, led by the ADR-0001 clause it encodes
+	clause string // the ADR text the rule enforces, quoted in failures
+	hint   string // one-line fix direction
+	// subject reports whether an importer is governed by the rule; the
+	// non-empty guard requires at least one governed package per rule.
+	subject func(from class, fromName string) bool
+	// forbids reports whether the rule rejects the edge.
+	forbids func(from, to class, fromName string) bool
+}
+
+// awsgwRole is the composition root ADR-0002 lets wire domain registrations.
+const awsgwRole = "runtime/roles/awsgw"
+
+// qualificationBinaries are the developer/qualification mains ADR-0001 lets
+// keep reusable source in internal/testkit or internal/tooling.
+var qualificationBinaries = map[string]bool{
+	"cmd/aws-model-coverage": true, "cmd/dhcptest": true, "cmd/spx-loadgen": true,
+}
+
+func isLayer(c class, layers ...layer) bool {
+	return slices.Contains(layers, c.layer)
+}
+
+// importsDomainImplementation is any domain-owned package other than a named
+// projection, in its target or legacy home.
+func importsDomainImplementation(to class) bool {
+	return to.domainShaped() && to.kind != domainProj
+}
+
+var rules = []rule{
+	{
+		id:      "R1_FoundationImportsOnlyFoundation",
+		clause:  "rule 1: foundation imports neither domains, ingress, runtime nor operator (enforced conservatively: foundation imports no module package above foundation)",
+		hint:    "move the dependency's needed primitive into foundation or invert it through a parameter",
+		subject: func(f class, _ string) bool { return f.layer == layerFoundation },
+		forbids: func(_, t class, _ string) bool { return t.layer != layerFoundation },
+	},
+	{
+		id:      "R2_IngressImportsNoImplementation",
+		clause:  "rule 2: ingress/aws imports no domain implementation; domains supply their own action registration through the ingress registration contract",
+		hint:    "take the capability through the registration contract wired by runtime/roles/awsgw",
+		subject: func(f class, _ string) bool { return f.layer == layerIngress },
+		forbids: func(_, t class, _ string) bool {
+			return !isLayer(t, layerFoundation, layerContracts, layerIngress)
+		},
+	},
+	{
+		id:      "R3_DomainImportsNoOtherDomainImplementation",
+		clause:  "rule 3: a domain does not read another domain's private records, migrations or repository; it uses a consumer-owned capability, a named projection, or a versioned contracts/<domain>/v1 contract",
+		hint:    "declare a narrow capability in the consumer, or import the owner's projection or contracts/<domain>/v1",
+		subject: func(f class, _ string) bool { return f.domainShaped() },
+		forbids: func(f, t class, _ string) bool {
+			return f.domainShaped() && importsDomainImplementation(t) && t.domain != f.domain
+		},
+	},
+	{
+		id:      "R4_ProviderImportsNoDomainImplementation",
+		clause:  "rule 4: a provider adapter implements a provider contract and cannot acquire AWS-visible resource authority by reading a domain's private state",
+		hint:    "pass the needed values into the provider contract instead of importing the domain",
+		subject: func(f class, _ string) bool { return f.layer == layerProviders },
+		forbids: func(_, t class, _ string) bool { return t.domainShaped() || t.isLegacy() },
+	},
+	{
+		id:      "R5_DomainImportsNoRuntimeOrOperator",
+		clause:  "rule 5: operator and runtime are composition consumers; they wire domain modules, so a domain does not import them",
+		hint:    "expose the runtime or operator state through a domain-owned projection or a capability wired at the composition root",
+		subject: func(f class, _ string) bool { return f.domainShaped() },
+		forbids: func(f, t class, _ string) bool {
+			return f.domainShaped() && (isLayer(t, layerRuntime, layerOperator) ||
+				t.isLegacy(runtimeLegacy...) || t.isLegacy(operatorLegacy...))
+		},
+	},
+	{
+		id:      "R5_AWSAPIAdaptersImportedOnlyByOwnerOrComposition",
+		clause:  "rule 5: operator and runtime call public use cases; a domain's awsapi action adapters are owned by that domain and wired only by the composition root",
+		hint:    "call an owner-provided capability instead of the AWS action adapter",
+		subject: func(_ class, _ string) bool { return true },
+		forbids: func(f, t class, fromName string) bool {
+			if t.kind != domainAWSAPI || fromName == awsgwRole {
+				return false
+			}
+			return !f.domainShaped() || f.domain != t.domain
+		},
+	},
+	{
+		id:      "R5_OperatorImportsNoLegacyImplementation",
+		clause:  "rule 5 and the cmd/spinifex map row: operator use cases reach domains through public capabilities and do not read domain-private state",
+		hint:    "reach the domain through its public capability; do not import a legacy implementation root",
+		subject: func(f class, _ string) bool { return f.layer == layerOperator },
+		forbids: func(f, t class, _ string) bool { return f.layer == layerOperator && t.isLegacy() },
+	},
+	{
+		id:      "R6_ProductionImportsNoTestkit",
+		clause:  "rule 6: test support is under internal/testkit; production packages do not import it",
+		hint:    "move the shared code to its production owner or keep the import in a _test.go file",
+		subject: func(f class, n string) bool { return f.layer != layerTestkit && !qualificationBinaries[n] },
+		forbids: func(f, t class, n string) bool {
+			return f.layer != layerTestkit && !qualificationBinaries[n] && isLayer(t, layerTestkit, layerTests)
+		},
+	},
+	{
+		id:      "Contracts_ImportOnlyFoundationAndContracts",
+		clause:  "decision item 1 and the area table: contracts own cross-process vocabulary, not application interfaces, domain persistence or transport implementation",
+		hint:    "keep wire types self-contained; depend only on foundation or another contract",
+		subject: func(f class, _ string) bool { return f.layer == layerContracts },
+		forbids: func(_, t class, _ string) bool { return !isLayer(t, layerFoundation, layerContracts) },
+	},
+	{
+		id:      "Domains_ImportNoAgentsIngressOrLegacy",
+		clause:  "area table and domain module shape: a domain owns no other domain's implementation; only its awsapi adapters may use the generic ingress/aws machinery",
+		hint:    "depend on a contract or capability; leave ingress use to the domain's awsapi package",
+		subject: func(f class, _ string) bool { return f.domainShaped() },
+		forbids: func(f, t class, _ string) bool {
+			if !f.domainShaped() {
+				return false
+			}
+			switch {
+			case t.layer == layerAgents || t.isLegacy("lbagent"):
+				return true
+			case t.layer == layerIngress:
+				return f.kind != domainAWSAPI && f.kind != legacyAdapter
+			case t.isLegacy("gateway") && !t.domainShaped():
+				return true
+			case t.isLegacy("handlers", "gateway"):
+				return f.layer == layerDomain
+			}
+			return false
+		},
+	},
+	{
+		id:      "Agents_ImportNoDomainOrLegacyImplementation",
+		clause:  "area table: agents/<domain> own in-guest and service-role behaviour, not tenant API authority or another domain's private state",
+		hint:    "move the shared wire vocabulary behind a guest/controller contract under contracts/",
+		subject: func(f class, _ string) bool { return f.layer == layerAgents || f.isLegacy("lbagent") },
+		forbids: func(f, t class, _ string) bool {
+			return (f.layer == layerAgents || f.isLegacy("lbagent")) && (t.domainShaped() || t.isLegacy())
+		},
+	},
+	{
+		id:      "Q22_STSImportsNoEKSImplementation",
+		clause:  "Q-22 prohibits the STS-to-EKS dependency in its present form; cut it through an identity-owned contract or an EKS projection",
+		hint:    "consume an EKS projection or an identity-owned contract instead of the EKS implementation",
+		subject: func(f class, _ string) bool { return f.domainShaped() && f.domain == "sts" },
+		forbids: func(f, t class, _ string) bool {
+			return f.domainShaped() && f.domain == "sts" && t.domain == "eks" &&
+				(importsDomainImplementation(t) || t.layer == layerAgents)
+		},
+	},
+	{
+		id:      "Interim_DaemonGatewayHandlersDirection",
+		clause:  "during migration the existing daemon -> gateway -> handlers rule remains the guardrail (Q-20, Q-29)",
+		hint:    "keep the dependency pointing daemon -> gateway -> handlers; invert it through a callback or capability",
+		subject: func(f class, _ string) bool { return f.isLegacy("handlers", "gateway") },
+		forbids: func(f, t class, _ string) bool {
+			switch {
+			case f.isLegacy("handlers"):
+				return t.isLegacy("gateway", "daemon")
+			case f.isLegacy("gateway"):
+				return t.isLegacy("daemon")
+			}
+			return false
+		},
+	},
+}

build/Dockerfile.distro

@@ -1,6 +1,6 @@
 ARG VERSION=dev
 
-FROM golang:1.27-bookworm AS builder
+FROM golang:1.27.3-bookworm@sha256:5c3e9b43cfd3bb95c7937462e29d87ada57b481a96fa23ad0eb61778d7a00110 AS builder
 
 ARG VERSION
 
@@ -35,8 +35,8 @@ COPY bluebottle/ ./bluebottle/
 # Build spinifex binary (spx)
 RUN COMMIT=$(cd spinifex && git rev-parse --short HEAD 2>/dev/null || echo "unknown") && \
     cd spinifex && GOFIPS140=v1.0.0 go build -ldflags "-s -w \
-    -X github.com/mulgadc/spinifex/cmd/spinifex/cmd.Version=${VERSION} \
-    -X github.com/mulgadc/spinifex/cmd/spinifex/cmd.Commit=${COMMIT}" \
+    -X github.com/mulgadc/spinifex/spinifex/operator/cli.Version=${VERSION} \
+    -X github.com/mulgadc/spinifex/spinifex/operator/cli.Commit=${COMMIT}" \
     -o /out/spx cmd/spinifex/main.go
 
 # Build nbdkit viperblock plugin (.so)

build/systemd/spinifex-ui.service

@@ -1,4 +1,4 @@
-# spinifex-unit-version: 1
+# spinifex-unit-version: 2
 [Unit]
 Description=Spinifex Web UI
 PartOf=spinifex.target
@@ -24,6 +24,7 @@ MemoryMax=20%
 Environment=SPINIFEX_UI_TLS_CERT=/etc/spinifex/server.pem
 Environment=SPINIFEX_UI_TLS_KEY=/etc/spinifex/server.key
 Environment=SPINIFEX_UI_BASE_DIR=/var/lib/spinifex/spinifex-ui/
+Environment=SPINIFEX_UI_OCHRE_ENABLED=false
 
 # Filesystem access
 NoNewPrivileges=yes

cmd/aws-model-coverage/main.go

@@ -1,18 +1,60 @@
 package main
 
 import (
+	"flag"
 	"fmt"
 	"os"
 
+	"github.com/mulgadc/predastore/s3api"
 	"github.com/mulgadc/spinifex/internal/awsmodel"
+	acmawsapi "github.com/mulgadc/spinifex/spinifex/domains/acm/awsapi"
+	awsapi "github.com/mulgadc/spinifex/spinifex/domains/ecr/awsapi"
 	"github.com/mulgadc/spinifex/spinifex/gateway"
+	"github.com/mulgadc/spinifex/spinifex/ingress/aws/dispatch"
+
+	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
 )
 
 func main() {
-	dispatch := gateway.AWSOperationInventory()
+	outputDir := flag.String("out", "", "write one publishable page per service into this directory")
+	jsonOutput := flag.String("json", "", "write a machine-readable coverage inventory to this file")
+	flag.Parse()
+
+	coverages, err := compareAll()
+	if err != nil {
+		fail(err)
+	}
+	if *outputDir == "" && *jsonOutput == "" {
+		fmt.Print(awsmodel.RenderCoverageSummary(coverages))
+		return
+	}
+	if *outputDir != "" {
+		if err := awsmodel.WritePages(*outputDir, coverages); err != nil {
+			fail(err)
+		}
+	}
+	if *jsonOutput != "" {
+		if err := awsmodel.WriteCoverageJSON(*jsonOutput, coverages); err != nil {
+			fail(err)
+		}
+	}
+}
+
+func fail(err error) {
+	fmt.Fprintf(os.Stderr, "aws-model-coverage: %v\n", err)
+	os.Exit(1)
+}
+
+func compareAll() ([]awsmodel.OperationCoverage, error) {
+	// Registered services contribute their declared inventory, which needs no
+	// live dependencies; nothing here serves a request.
+	inventories := gateway.AWSOperationInventory(map[string]dispatch.Inventory{
+		awsapi.ServiceName:    awsapi.OperationInventory(),
+		acmawsapi.ServiceName: acmawsapi.OperationInventory(),
+	})
 	coverages := make([]awsmodel.OperationCoverage, 0, len(awsmodel.Services()))
 	for _, service := range awsmodel.Services() {
-		inventory, ok := dispatch[string(service)]
+		inventory, ok := inventories[string(service)]
 		var modelInventory awsmodel.DispatchInventory
 		switch {
 		case ok:
@@ -21,23 +63,19 @@ func main() {
 				Stubbed:     inventory.Stubbed,
 				Unsupported: inventory.Unsupported,
 			}
+		// Predastore serves the S3 REST surface, and names the operations each
+		// of its routes answers, so the comparison is the same one.
 		case service == awsmodel.S3:
-			modelInventory = awsmodel.DispatchInventory{
-				Opaque: true,
-				Note:   "Spinifex delegates the S3 REST surface to Predastore, which has no operation-name dispatch table to compare mechanically.",
-			}
+			modelInventory = awsmodel.DispatchInventory{Registered: s3api.Operations()}
 		default:
-			fmt.Fprintf(os.Stderr, "aws-model-coverage: no gateway inventory for %s\n", service)
-			os.Exit(1)
+			return nil, fmt.Errorf("no gateway inventory for %s", service)
 		}
 
 		coverage, err := awsmodel.CompareOperations(service, modelInventory)
 		if err != nil {
-			fmt.Fprintf(os.Stderr, "aws-model-coverage: %v\n", err)
-			os.Exit(1)
+			return nil, err
 		}
 		coverages = append(coverages, coverage)
 	}
-
-	fmt.Print(awsmodel.RenderCoverageMarkdown(coverages))
+	return coverages, nil
 }

cmd/dhcptest/main.go

@@ -23,7 +23,9 @@ import (
 
 	"github.com/insomniacslk/dhcp/dhcpv4"
 	"github.com/insomniacslk/dhcp/dhcpv4/nclient4"
-	"github.com/mulgadc/spinifex/spinifex/network/external/dhcp"
+	"github.com/mulgadc/spinifex/spinifex/domains/network/external/dhcp"
+
+	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
 )
 
 func main() {

cmd/ecr-credential-provider/main.go

@@ -1,175 +1,15 @@
-// ecr-credential-provider is a kubelet exec credential provider that lets a
-// Spinifex EKS worker node pull images from the internal Spinifex ECR registry.
-//
-// kubelet invokes it per-pull, feeding a CredentialProviderRequest on STDIN and
-// reading a CredentialProviderResponse on STDOUT. The provider fetches the
-// node IAM-role credentials from IMDS, SigV4-signs GetAuthorizationToken against
-// the AWS gateway's ECR endpoint, and returns the minted AWS:<jwt> as Basic auth
-// for the requested registry host.
-//
-// Static node config (gateway URL, CA, region) is read from the cloud-init env
-// file /etc/spinifex-eks/agent.env (KEY=value); real env vars override it.
+// ecr-credential-provider is the kubelet exec credential provider for Spinifex
+// EKS worker nodes; the implementation is in agents/eks/credentialprovider.
 package main
 
 import (
-	"encoding/json"
-	"fmt"
-	"io"
-	"log/slog"
-	"net/http"
 	"os"
-	"time"
 
-	"github.com/mulgadc/spinifex/internal/ecrauth"
-	"github.com/mulgadc/spinifex/internal/guestenv"
-	"github.com/mulgadc/spinifex/internal/imdscreds"
+	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
 
-	_ "github.com/mulgadc/spinifex/internal/fipsboot"
+	"github.com/mulgadc/spinifex/spinifex/agents/eks/credentialprovider"
 )
 
-const (
-	credProviderAPIVersion = "credentialprovider.kubelet.k8s.io/v1"
-	defaultCacheDuration   = "10h"
-	// expiryMargin trims the token's real TTL so kubelet re-invokes the provider
-	// before the JWT actually expires mid-run.
-	expiryMargin = 30 * time.Minute
-
-	defaultEnvFile   = "/etc/spinifex-eks/agent.env"
-	defaultGatewayCA = "/etc/spinifex-eks/gateway-ca.pem"
-	defaultIMDSBase  = "http://169.254.169.254/latest"
-)
-
-// CredentialProviderRequest is the kubelet exec-provider request on STDIN.
-type CredentialProviderRequest struct {
-	APIVersion string `json:"apiVersion"`
-	Kind       string `json:"kind"`
-	Image      string `json:"image"`
-}
-
-// AuthConfig is a single registry credential entry.
-type AuthConfig struct {
-	Username string `json:"username"`
-	Password string `json:"password"`
-}
-
-// CredentialProviderResponse is the kubelet exec-provider response on STDOUT.
-type CredentialProviderResponse struct {
-	APIVersion    string                `json:"apiVersion"`
-	Kind          string                `json:"kind"`
-	CacheKeyType  string                `json:"cacheKeyType"`
-	CacheDuration string                `json:"cacheDuration"`
-	Auth          map[string]AuthConfig `json:"auth"`
-}
-
-// config holds the static node settings the provider needs.
-type config struct {
-	GatewayURL string
-	GatewayCA  string
-	Region     string
-	IMDSBase   string
-}
-
 func main() {
-	cfg := loadConfig(defaultEnvFile)
-
-	httpClient, err := ecrauth.GatewayHTTPClient(cfg.GatewayCA)
-	if err != nil {
-		slog.Error("ecr-credential-provider: build gateway client", "err", err)
-		emitEmpty(os.Stdout)
-		os.Exit(1)
-	}
-
-	if err := run(os.Stdin, os.Stdout, cfg, httpClient); err != nil {
-		slog.Error("ecr-credential-provider: run failed", "err", err)
-		// Still emit a valid empty-auth response so kubelet has a parseable reply.
-		emitEmpty(os.Stdout)
-		os.Exit(1)
-	}
-}
-
-// run is the testable core: it reads a CredentialProviderRequest from in,
-// resolves credentials via IMDS + the gateway, and writes a
-// CredentialProviderResponse to out. The httpClient must trust the gateway CA.
-func run(in io.Reader, out io.Writer, cfg config, httpClient *http.Client) error {
-	var req CredentialProviderRequest
-	if err := json.NewDecoder(in).Decode(&req); err != nil {
-		return fmt.Errorf("decode request: %w", err)
-	}
-	if req.Image == "" {
-		return fmt.Errorf("request image is empty")
-	}
-	imageHost := ecrauth.HostFromImage(req.Image)
-
-	creds, err := imdscreds.Fetch(httpClient, cfg.IMDSBase)
-	if err != nil {
-		return fmt.Errorf("fetch IMDS credentials: %w", err)
-	}
-
-	tok, err := ecrauth.GetAuthorizationToken(cfg.Region, cfg.GatewayURL, httpClient,
-		creds.AccessKeyID, creds.SecretAccessKey, creds.SessionToken)
-	if err != nil {
-		return fmt.Errorf("get authorization token: %w", err)
-	}
-
-	auth := AuthConfig{Username: tok.Username, Password: tok.Password}
-	authMap := map[string]AuthConfig{imageHost: auth}
-	if tok.ProxyHost != "" && tok.ProxyHost != imageHost {
-		authMap[tok.ProxyHost] = auth
-	}
-
-	resp := CredentialProviderResponse{
-		APIVersion:    credProviderAPIVersion,
-		Kind:          "CredentialProviderResponse",
-		CacheKeyType:  "Registry",
-		CacheDuration: cacheDurationFrom(tok.ExpiresAt),
-		Auth:          authMap,
-	}
-	return json.NewEncoder(out).Encode(&resp)
-}
-
-// cacheDurationFrom derives a Go-duration string from the token expiry minus a
-// safety margin, falling back to the default when expiry is unknown or too near.
-func cacheDurationFrom(expiresAt time.Time) string {
-	if expiresAt.IsZero() {
-		return defaultCacheDuration
-	}
-	d := time.Until(expiresAt) - expiryMargin
-	if d <= 0 {
-		return defaultCacheDuration
-	}
-	return d.Round(time.Second).String()
-}
-
-// loadConfig reads the cloud-init env file then lets real env vars override. The
-// IMDS base is fixed (not in the env file) but overridable for tests.
-func loadConfig(envFile string) config {
-	get := guestenv.Load(envFile).Get
-
-	cfg := config{
-		GatewayURL: get("EKS_GATEWAY_URL"),
-		GatewayCA:  get("EKS_GATEWAY_CA"),
-		Region:     get("EKS_REGION"),
-		IMDSBase:   get("EKS_IMDS_BASE"),
-	}
-	if cfg.GatewayCA == "" {
-		cfg.GatewayCA = defaultGatewayCA
-	}
-	if cfg.IMDSBase == "" {
-		cfg.IMDSBase = defaultIMDSBase
-	}
-	return cfg
-}
-
-// emitEmpty writes a valid CredentialProviderResponse with no auth entries.
-func emitEmpty(out io.Writer) {
-	resp := CredentialProviderResponse{
-		APIVersion:    credProviderAPIVersion,
-		Kind:          "CredentialProviderResponse",
-		CacheKeyType:  "Registry",
-		CacheDuration: defaultCacheDuration,
-		Auth:          map[string]AuthConfig{},
-	}
-	if err := json.NewEncoder(out).Encode(&resp); err != nil {
-		slog.Error("ecr-credential-provider: encode empty response", "err", err)
-	}
+	os.Exit(credentialprovider.Main(os.Stdin, os.Stdout))
 }

cmd/ecr-credential-provider/main_test.go

@@ -1,126 +0,0 @@
-package main
-
-import (
-	"bytes"
-	"crypto/tls"
-	"crypto/x509"
-	"encoding/base64"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"testing"
-)
-
-// fakeBackend serves both the IMDS role/credentials endpoints and the gateway
-// ECR GetAuthorizationToken on one TLS server, routed by request path.
-func fakeBackend(t *testing.T) *httptest.Server {
-	t.Helper()
-	mux := http.NewServeMux()
-
-	// IMDSv2 token. Real IMDS echoes the requested TTL back as a response
-	// header; the SDK client parses it from there, not the body.
-	mux.HandleFunc("/latest/api/token", func(w http.ResponseWriter, r *http.Request) {
-		if r.Method != http.MethodPut {
-			w.WriteHeader(http.StatusMethodNotAllowed)
-			return
-		}
-		w.Header().Set("X-Aws-Ec2-Metadata-Token-Ttl-Seconds", "21600")
-		_, _ = w.Write([]byte("imds-v2-token"))
-	})
-	// IMDS role name.
-	mux.HandleFunc("/latest/meta-data/iam/security-credentials/", func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path == "/latest/meta-data/iam/security-credentials/" {
-			if r.Header.Get("X-Aws-Ec2-Metadata-Token") != "imds-v2-token" {
-				w.WriteHeader(http.StatusUnauthorized)
-				return
-			}
-			_, _ = w.Write([]byte("node-role"))
-			return
-		}
-		// Role credentials.
-		_ = json.NewEncoder(w).Encode(map[string]string{
-			"Code":            "Success",
-			"Type":            "AWS-HMAC",
-			"AccessKeyId":     "AKIATEST",
-			"SecretAccessKey": "secrettest",
-			"Token":           "sessiontoken",
-			"AccountId":       "123456789012",
-		})
-	})
-	// Gateway ECR GetAuthorizationToken (X-Amz-Target dispatch).
-	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
-		if !strings.Contains(r.Header.Get("X-Amz-Target"), "GetAuthorizationToken") {
-			w.WriteHeader(http.StatusBadRequest)
-			return
-		}
-		authToken := base64.StdEncoding.EncodeToString([]byte("AWS:testjwt"))
-		w.Header().Set("Content-Type", "application/x-amz-json-1.1")
-		_ = json.NewEncoder(w).Encode(map[string]any{
-			"authorizationData": []map[string]any{{
-				"authorizationToken": authToken,
-				"proxyEndpoint":      "https://123456789012.dkr.ecr.us-east-1.spinifex.internal",
-			}},
-		})
-	})
-
-	srv := httptest.NewTLSServer(mux)
-	t.Cleanup(srv.Close)
-	return srv
-}
-
-func clientTrusting(srv *httptest.Server) *http.Client {
-	pool := x509.NewCertPool()
-	pool.AddCert(srv.Certificate())
-	return &http.Client{Transport: &http.Transport{TLSClientConfig: &tls.Config{RootCAs: pool, MinVersion: tls.VersionTLS12}}}
-}
-
-func TestRun_ReturnsBasicAuth(t *testing.T) {
-	srv := fakeBackend(t)
-	client := clientTrusting(srv)
-
-	cfg := config{
-		GatewayURL: srv.URL,
-		Region:     "us-east-1",
-		IMDSBase:   srv.URL + "/latest",
-	}
-
-	const image = "123456789012.dkr.ecr.us-east-1.spinifex.internal/spinifex-demo:latest"
-	reqBody, err := json.Marshal(CredentialProviderRequest{
-		APIVersion: credProviderAPIVersion,
-		Kind:       "CredentialProviderRequest",
-		Image:      image,
-	})
-	if err != nil {
-		t.Fatalf("marshal request: %v", err)
-	}
-
-	var out bytes.Buffer
-	if err := run(bytes.NewReader(reqBody), &out, cfg, client); err != nil {
-		t.Fatalf("run: %v", err)
-	}
-
-	var resp CredentialProviderResponse
-	if err := json.Unmarshal(out.Bytes(), &resp); err != nil {
-		t.Fatalf("unmarshal response: %v\n%s", err, out.String())
-	}
-
-	if resp.Kind != "CredentialProviderResponse" {
-		t.Errorf("Kind = %q, want CredentialProviderResponse", resp.Kind)
-	}
-	if resp.CacheKeyType != "Registry" {
-		t.Errorf("CacheKeyType = %q, want Registry", resp.CacheKeyType)
-	}
-
-	host := "123456789012.dkr.ecr.us-east-1.spinifex.internal"
-	auth, ok := resp.Auth[host]
-	if !ok {
-		t.Fatalf("auth map missing host %q; got %v", host, resp.Auth)
-	}
-	if auth.Username != "AWS" {
-		t.Errorf("username = %q, want AWS", auth.Username)
-	}
-	if auth.Password != "testjwt" {
-		t.Errorf("password = %q, want testjwt", auth.Password)
-	}
-}

cmd/ecs-agent/agent.go

@@ -1,198 +0,0 @@
-package main
-
-import (
-	"bufio"
-	"context"
-	"fmt"
-	"log/slog"
-	"net/http"
-	"os"
-	goruntime "runtime"
-	"strconv"
-	"strings"
-	"time"
-
-	"github.com/mulgadc/spinifex/cmd/ecs-agent/credentials"
-	ctrruntime "github.com/mulgadc/spinifex/cmd/ecs-agent/runtime"
-	"github.com/mulgadc/spinifex/spinifex/handlers/ecs/bus"
-)
-
-// version is the agent build version, reported in the register message.
-// Overridable via -ldflags "-X main.version=...".
-var version = "dev"
-
-// Agent wires the ecs-agent's runtime seams: a gateway control-plane client, a
-// container runtime, and an ECR resolver. It registers the host as a container
-// instance at boot, heartbeats (re-registers) while alive, polls the gateway for
-// task assignments, and runs them through containerd, reporting state back over
-// the gateway. It never connects to NATS — the bus stays host-internal.
-type Agent struct {
-	cfg      config
-	id       identity
-	cp       controlPlane
-	puller   ctrruntime.ImagePuller
-	runner   ctrruntime.Runner
-	resolver ctrruntime.Resolver
-
-	reg *registrar
-	hb  *heartbeater
-
-	// netns builds awsvpc task network namespaces (nil-safe; bridge/host skip it).
-	netns *taskNetns
-
-	// cred serves task IAM role credentials at 169.254.170.2 (nil in unit tests).
-	cred *credEndpoint
-
-	// gpu is the local pinning ledger over the host's discovered GPU UUIDs.
-	// Always non-nil (newAgent seeds an empty one); New() reseeds it from
-	// nvidia-smi discovery.
-	gpu *gpuLedger
-
-	closers []func() error
-}
-
-// newAgent assembles an Agent from already-built seams. Tests use this directly
-// with fakes; New builds the production seams and delegates here. runner may be
-// nil when containerd is unavailable; the assign path then reports the task
-// STOPPED rather than crashing.
-func newAgent(cfg config, id identity, cp controlPlane, puller ctrruntime.ImagePuller, runner ctrruntime.Runner, resolver ctrruntime.Resolver) *Agent {
-	return &Agent{
-		cfg:      cfg,
-		id:       id,
-		cp:       cp,
-		puller:   puller,
-		runner:   runner,
-		resolver: resolver,
-		reg:      newRegistrar(cp, id),
-		hb:       newHeartbeater(cp, id, cfg.Heartbeat),
-		netns:    newTaskNetns(execNetRunner{}),
-		gpu:      newGPULedger(id.Capacity.GPUIDs),
-	}
-}
-
-// New builds an Agent from config: it resolves the host identity from IMDS,
-// builds the gateway control-plane client, the ECR resolver and (best-effort)
-// the containerd runtime. A containerd connect failure is logged, not fatal —
-// registration and heartbeat still run so the instance is visible while the
-// runtime recovers. The ECR gateway client is built lazily on first image pull
-// (not here), so a missing or malformed gateway CA does not stop registration.
-func New(cfg config) (*Agent, error) {
-	imdsClient := &http.Client{Timeout: 5 * time.Second}
-
-	meta, err := fetchInstanceMetadata(imdsClient, cfg.IMDSBase)
-	if err != nil {
-		return nil, fmt.Errorf("instance metadata: %w", err)
-	}
-	host, _ := os.Hostname()
-	id := identity{
-		AccountID:    meta.AccountID,
-		ClusterName:  cfg.ClusterName,
-		InstanceID:   meta.InstanceID,
-		AZ:           meta.AZ,
-		Hostname:     host,
-		Capacity:     detectCapacity(discoverNvidiaGPUs(execCommandRunner)),
-		AgentVersion: version,
-	}
-
-	creds := credentials.NewIMDSProvider(imdsClient, cfg.IMDSBase)
-	resolver := newLazyECRResolver(creds, cfg.Region, cfg.GatewayURL, cfg.GatewayCA)
-
-	var puller ctrruntime.ImagePuller
-	var runner ctrruntime.Runner
-	if rt, perr := ctrruntime.New(cfg.ContainerdSocket); perr != nil {
-		slog.Warn("ecs-agent: containerd unavailable at boot, image pulls disabled", "err", perr)
-	} else {
-		puller = rt
-		runner = rt
-	}
-
-	cp, err := newGatewayControlPlane(cfg, creds)
-	if err != nil {
-		return nil, fmt.Errorf("build gateway control-plane: %w", err)
-	}
-
-	a := newAgent(cfg, id, cp, puller, runner, resolver)
-	a.cred = newCredEndpoint(creds, cfg.Region, cfg.GatewayURL, cfg.GatewayCA,
-		cfg.CredEndpointIP, cfg.CredEndpointPort, execNetRunner{})
-	if puller != nil {
-		a.closers = append(a.closers, puller.Close)
-	}
-	return a, nil
-}
-
-// Run registers the instance, starts the heartbeat and assignment-poll loops,
-// and blocks until ctx is cancelled, then tears down.
-func (a *Agent) Run(ctx context.Context) error {
-	if err := a.reg.Register(); err != nil {
-		slog.Error("ecs-agent: initial registration failed", "err", err)
-	} else {
-		slog.Info("ecs-agent: registered", "cluster", a.id.ClusterName, "instance", a.id.InstanceID)
-	}
-
-	if a.cred != nil {
-		if err := a.cred.Start(); err != nil {
-			slog.Error("ecs-agent: credential endpoint start failed", "err", err)
-		}
-	}
-
-	go a.hb.Run(ctx)
-
-	// Re-adopt containers still running from before this restart, then poll with
-	// their tasks pre-seeded so re-delivered assignments are acked, not re-run.
-	go a.pollAssignments(ctx, a.reconcile(ctx))
-
-	<-ctx.Done()
-	return a.Stop()
-}
-
-// Stop closes the runtime. Safe to call once.
-func (a *Agent) Stop() error {
-	var firstErr error
-	if a.cred != nil {
-		_ = a.cred.Stop()
-	}
-	for _, c := range a.closers {
-		if err := c(); err != nil && firstErr == nil {
-			firstErr = err
-		}
-	}
-	return firstErr
-}
-
-// detectCapacity reports the host's total CPU units (1 vCPU = 1024), memory,
-// and GPU count/UUIDs from the caller's nvidia-smi discovery (nil on a
-// non-GPU host).
-func detectCapacity(gpuUUIDs []string) bus.InstanceCapacity {
-	return bus.InstanceCapacity{
-		CPU:       goruntime.NumCPU() * 1024,
-		MemoryMiB: memTotalMiB(),
-		GPU:       len(gpuUUIDs),
-		GPUIDs:    gpuUUIDs,
-	}
-}
-
-// memTotalMiB reads MemTotal from /proc/meminfo, returning 0 if unavailable.
-func memTotalMiB() int {
-	f, err := os.Open("/proc/meminfo")
-	if err != nil {
-		return 0
-	}
-	defer f.Close()
-	scanner := bufio.NewScanner(f)
-	for scanner.Scan() {
-		line := scanner.Text()
-		if !strings.HasPrefix(line, "MemTotal:") {
-			continue
-		}
-		fields := strings.Fields(line)
-		if len(fields) < 2 {
-			return 0
-		}
-		kb, err := strconv.Atoi(fields[1])
-		if err != nil {
-			return 0
-		}
-		return kb / 1024
-	}
-	return 0
-}

cmd/ecs-agent/agent_test.go

@@ -1,66 +0,0 @@
-package main
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	ctrruntime "github.com/mulgadc/spinifex/cmd/ecs-agent/runtime"
-)
-
-func TestAgent_RunRegistersThenStopsOnContext(t *testing.T) {
-	cp := &fakeCP{}
-	cfg := config{Heartbeat: 5 * time.Millisecond, PollInterval: 5 * time.Millisecond}
-	puller := &ctrruntime.FakePuller{}
-	a := newAgent(cfg, testIdentity(), cp, puller, puller, nil)
-	a.closers = append(a.closers, puller.Close)
-
-	ctx, cancel := context.WithCancel(context.Background())
-	done := make(chan error, 1)
-	go func() { done <- a.Run(ctx) }()
-
-	// Give it time to register + re-register (heartbeat) a few times.
-	time.Sleep(30 * time.Millisecond)
-	cancel()
-
-	select {
-	case err := <-done:
-		if err != nil {
-			t.Fatalf("Run returned error: %v", err)
-		}
-	case <-time.After(time.Second):
-		t.Fatal("Run did not return after cancel")
-	}
-
-	// One boot register + at least one heartbeat re-register.
-	if cp.registerCount() < 2 {
-		t.Errorf("registers = %d, want >= 2 (boot + heartbeat)", cp.registerCount())
-	}
-	if !puller.Closed {
-		t.Error("Stop did not close the puller")
-	}
-}
-
-func TestDetectCapacity_Positive(t *testing.T) {
-	c := detectCapacity(nil)
-	if c.CPU <= 0 {
-		t.Errorf("CPU = %d, want > 0", c.CPU)
-	}
-	// MemoryMiB may be 0 on platforms without /proc/meminfo; just assert non-negative.
-	if c.MemoryMiB < 0 {
-		t.Errorf("MemoryMiB = %d, want >= 0", c.MemoryMiB)
-	}
-	if c.GPU != 0 || c.GPUIDs != nil {
-		t.Errorf("no GPU UUIDs given: want GPU=0/GPUIDs=nil, got %d/%v", c.GPU, c.GPUIDs)
-	}
-}
-
-func TestDetectCapacity_WithGPUUUIDs(t *testing.T) {
-	c := detectCapacity([]string{"GPU-aaa", "GPU-bbb"})
-	if c.GPU != 2 {
-		t.Errorf("GPU = %d, want 2", c.GPU)
-	}
-	if len(c.GPUIDs) != 2 {
-		t.Errorf("GPUIDs = %v, want 2 entries", c.GPUIDs)
-	}
-}

cmd/ecs-agent/config.go

@@ -1,89 +0,0 @@
-package main
-
-import (
-	"strconv"
-	"time"
-
-	"github.com/mulgadc/spinifex/internal/guestenv"
-)
-
-const (
-	defaultEnvFile          = "/etc/spinifex-ecs/agent.env"
-	defaultGatewayCA        = "/etc/spinifex-ecs/gateway-ca.pem"
-	defaultIMDSBase         = "http://169.254.169.254/latest"
-	defaultContainerdSocket = "/run/containerd/containerd.sock"
-	defaultHeartbeat        = 30 * time.Second
-	defaultPollInterval     = 5 * time.Second
-)
-
-// config holds the static settings the agent reads at boot. Cluster identity
-// (account ID, instance ID) is discovered at runtime from IMDS, not configured;
-// only the cluster *name* the instance was launched into is static. AccessKey /
-// SecretKey are legacy seeded creds, optional now that the agent SigV4-signs
-// gateway calls with instance-role credentials from IMDS; the agent never holds
-// a NATS token.
-type config struct {
-	GatewayURL       string
-	GatewayCA        string
-	Region           string
-	ClusterName      string
-	AccessKey        string
-	SecretKey        string
-	IMDSBase         string
-	ContainerdSocket string
-	Heartbeat        time.Duration
-	PollInterval     time.Duration
-	CredEndpointIP   string
-	CredEndpointPort int
-}
-
-// loadConfig reads the cloud-init env file then lets real env vars override.
-func loadConfig(envFile string) config {
-	get := guestenv.Load(envFile).Get
-
-	cfg := config{
-		GatewayURL:       get("ECS_GATEWAY_URL"),
-		GatewayCA:        get("ECS_GATEWAY_CA"),
-		Region:           get("ECS_REGION"),
-		ClusterName:      get("ECS_CLUSTER"),
-		AccessKey:        get("ECS_ACCESS_KEY"),
-		SecretKey:        get("ECS_SECRET_KEY"),
-		IMDSBase:         get("ECS_IMDS_BASE"),
-		ContainerdSocket: get("ECS_CONTAINERD_SOCKET"),
-	}
-	if cfg.GatewayCA == "" {
-		cfg.GatewayCA = defaultGatewayCA
-	}
-	if cfg.IMDSBase == "" {
-		cfg.IMDSBase = defaultIMDSBase
-	}
-	if cfg.ContainerdSocket == "" {
-		cfg.ContainerdSocket = defaultContainerdSocket
-	}
-	if cfg.ClusterName == "" {
-		cfg.ClusterName = "default"
-	}
-	cfg.Heartbeat = defaultHeartbeat
-	if v := get("ECS_HEARTBEAT_INTERVAL"); v != "" {
-		if d, err := time.ParseDuration(v); err == nil && d > 0 {
-			cfg.Heartbeat = d
-		}
-	}
-	cfg.PollInterval = defaultPollInterval
-	if v := get("ECS_POLL_INTERVAL"); v != "" {
-		if d, err := time.ParseDuration(v); err == nil && d > 0 {
-			cfg.PollInterval = d
-		}
-	}
-	cfg.CredEndpointIP = get("ECS_CRED_ENDPOINT_IP")
-	if cfg.CredEndpointIP == "" {
-		cfg.CredEndpointIP = defaultCredEndpointIP
-	}
-	cfg.CredEndpointPort = defaultCredEndpointPort
-	if v := get("ECS_CRED_ENDPOINT_PORT"); v != "" {
-		if p, err := strconv.Atoi(v); err == nil && p > 0 {
-			cfg.CredEndpointPort = p
-		}
-	}
-	return cfg
-}

cmd/ecs-agent/config_test.go

@@ -1,73 +0,0 @@
-package main
-
-import (
-	"os"
-	"path/filepath"
-	"testing"
-	"time"
-)
-
-func TestLoadConfig_Defaults(t *testing.T) {
-	// Ensure env vars don't leak in from the host.
-	for _, k := range []string{"ECS_GATEWAY_URL", "ECS_GATEWAY_CA", "ECS_REGION",
-		"ECS_CLUSTER", "ECS_ACCESS_KEY", "ECS_SECRET_KEY", "ECS_IMDS_BASE",
-		"ECS_CONTAINERD_SOCKET", "ECS_HEARTBEAT_INTERVAL", "ECS_POLL_INTERVAL"} {
-		t.Setenv(k, "")
-	}
-	cfg := loadConfig(filepath.Join(t.TempDir(), "absent.env"))
-	if cfg.GatewayCA != defaultGatewayCA {
-		t.Errorf("GatewayCA = %q, want default", cfg.GatewayCA)
-	}
-	if cfg.IMDSBase != defaultIMDSBase {
-		t.Errorf("IMDSBase = %q, want default", cfg.IMDSBase)
-	}
-	if cfg.ContainerdSocket != defaultContainerdSocket {
-		t.Errorf("ContainerdSocket = %q, want default", cfg.ContainerdSocket)
-	}
-	if cfg.ClusterName != "default" {
-		t.Errorf("ClusterName = %q, want default", cfg.ClusterName)
-	}
-	if cfg.Heartbeat != defaultHeartbeat {
-		t.Errorf("Heartbeat = %v, want %v", cfg.Heartbeat, defaultHeartbeat)
-	}
-	if cfg.PollInterval != defaultPollInterval {
-		t.Errorf("PollInterval = %v, want %v", cfg.PollInterval, defaultPollInterval)
-	}
-}
-
-func TestLoadConfig_FileThenEnvOverride(t *testing.T) {
-	dir := t.TempDir()
-	envFile := filepath.Join(dir, "agent.env")
-	body := "# comment\nECS_GATEWAY_URL=https://gw.file\nECS_REGION=us-west-2\nECS_CLUSTER=prod\n"
-	if err := os.WriteFile(envFile, []byte(body), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	t.Setenv("ECS_GATEWAY_URL", "https://gw.env")
-	t.Setenv("ECS_ACCESS_KEY", "AKIAENV")
-
-	cfg := loadConfig(envFile)
-	if cfg.GatewayURL != "https://gw.env" {
-		t.Errorf("GatewayURL = %q, want env override", cfg.GatewayURL)
-	}
-	if cfg.Region != "us-west-2" {
-		t.Errorf("Region = %q, want from file", cfg.Region)
-	}
-	if cfg.ClusterName != "prod" {
-		t.Errorf("ClusterName = %q, want from file", cfg.ClusterName)
-	}
-	if cfg.AccessKey != "AKIAENV" {
-		t.Errorf("AccessKey = %q, want env", cfg.AccessKey)
-	}
-}
-
-func TestLoadConfig_HeartbeatOverride(t *testing.T) {
-	t.Setenv("ECS_HEARTBEAT_INTERVAL", "5s")
-	if cfg := loadConfig(filepath.Join(t.TempDir(), "absent.env")); cfg.Heartbeat != 5*time.Second {
-		t.Errorf("Heartbeat = %v, want 5s", cfg.Heartbeat)
-	}
-	// Garbage value falls back to the default, not zero.
-	t.Setenv("ECS_HEARTBEAT_INTERVAL", "not-a-duration")
-	if cfg := loadConfig(filepath.Join(t.TempDir(), "absent.env")); cfg.Heartbeat != defaultHeartbeat {
-		t.Errorf("Heartbeat = %v, want default on bad value", cfg.Heartbeat)
-	}
-}

cmd/ecs-agent/credentials/imds_test.go

@@ -1,107 +0,0 @@
-package credentials
-
-import (
-	"context"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"sync/atomic"
-	"testing"
-	"time"
-)
-
-// imdsStub serves the IMDSv2 token + role + credentials endpoints under the
-// real /latest prefix the SDK IMDS client always requests.
-func imdsStub(t *testing.T, hits *int32, creds map[string]string) *httptest.Server {
-	t.Helper()
-	mux := http.NewServeMux()
-	mux.HandleFunc("/latest/api/token", func(w http.ResponseWriter, r *http.Request) {
-		// Real IMDS echoes the requested TTL back as a response header; the SDK
-		// client parses it from there, not the body.
-		w.Header().Set("X-Aws-Ec2-Metadata-Token-Ttl-Seconds", "21600")
-		_, _ = w.Write([]byte("v2-token"))
-	})
-	mux.HandleFunc("/latest/meta-data/iam/security-credentials/", func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path == "/latest/meta-data/iam/security-credentials/" {
-			_, _ = w.Write([]byte("node-role"))
-			return
-		}
-		if hits != nil {
-			atomic.AddInt32(hits, 1)
-		}
-		_ = json.NewEncoder(w).Encode(creds)
-	})
-	srv := httptest.NewServer(mux)
-	t.Cleanup(srv.Close)
-	return srv
-}
-
-func TestRetrieve_FetchesAndCaches(t *testing.T) {
-	var hits int32
-	// Kept under an hour: ec2rolecreds caps Expires to now+1h.
-	exp := time.Now().Add(30 * time.Minute).UTC().Round(time.Second)
-	srv := imdsStub(t, &hits, map[string]string{
-		"Code":            "Success",
-		"AccessKeyId":     "AKIA",
-		"SecretAccessKey": "secret",
-		"Token":           "session",
-		"Expiration":      exp.Format(time.RFC3339),
-	})
-
-	p := NewIMDSProvider(srv.Client(), srv.URL+"/latest")
-	got, err := p.Retrieve(context.Background())
-	if err != nil {
-		t.Fatalf("Retrieve: %v", err)
-	}
-	if got.AccessKeyID != "AKIA" || !got.Expiration.Equal(exp) {
-		t.Errorf("creds mismatch: %+v", got)
-	}
-
-	// Second call well within validity must not re-hit IMDS.
-	if _, err := p.Retrieve(context.Background()); err != nil {
-		t.Fatalf("Retrieve 2: %v", err)
-	}
-	if hits != 1 {
-		t.Errorf("IMDS credential hits = %d, want 1 (cached)", hits)
-	}
-}
-
-func TestRetrieve_RefetchesWhenExpired(t *testing.T) {
-	var hits int32
-	// Already expired: aws.CredentialsCache refetches once the stored
-	// credentials' real expiry has passed, regardless of ExpiryWindow.
-	srv := imdsStub(t, &hits, map[string]string{
-		"Code":            "Success",
-		"AccessKeyId":     "AKIA",
-		"SecretAccessKey": "secret",
-		"Expiration":      time.Now().Add(-time.Minute).UTC().Format(time.RFC3339),
-	})
-	p := NewIMDSProvider(srv.Client(), srv.URL+"/latest")
-	if _, err := p.Retrieve(context.Background()); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := p.Retrieve(context.Background()); err != nil {
-		t.Fatal(err)
-	}
-	if hits != 2 {
-		t.Errorf("hits = %d, want 2 (expired refetch)", hits)
-	}
-}
-
-func TestRetrieve_CancelledContext(t *testing.T) {
-	srv := imdsStub(t, nil, map[string]string{"Code": "Success", "AccessKeyId": "A", "SecretAccessKey": "B"})
-	p := NewIMDSProvider(srv.Client(), srv.URL+"/latest")
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-	if _, err := p.Retrieve(ctx); err == nil {
-		t.Fatal("expected error from cancelled context")
-	}
-}
-
-func TestRetrieve_CodeNotSuccessErrors(t *testing.T) {
-	srv := imdsStub(t, nil, map[string]string{"Code": "Failure", "AccessKeyId": "A", "SecretAccessKey": "B"})
-	p := NewIMDSProvider(srv.Client(), srv.URL+"/latest")
-	if _, err := p.Retrieve(context.Background()); err == nil {
-		t.Fatal("expected error when Code != Success")
-	}
-}

cmd/ecs-agent/heartbeat.go

@@ -1,46 +0,0 @@
-package main
-
-import (
-	"context"
-	"log/slog"
-	"time"
-)
-
-// heartbeater keeps the container instance alive by periodically re-registering
-// it through the gateway. Real ECS folds liveness into ACS; v1 folds it into an
-// idempotent RegisterContainerInstance, which refreshes the instance's LastSeen
-// so the scheduler can tell live instances from dead ones (no bus.Heartbeat).
-type heartbeater struct {
-	cp       controlPlane
-	id       identity
-	interval time.Duration
-}
-
-func newHeartbeater(cp controlPlane, id identity, interval time.Duration) *heartbeater {
-	if interval <= 0 {
-		interval = defaultHeartbeat
-	}
-	return &heartbeater{cp: cp, id: id, interval: interval}
-}
-
-// beat re-registers the instance once, refreshing its LastSeen.
-func (h *heartbeater) beat() error {
-	return h.cp.Register(h.id)
-}
-
-// Run beats every interval until ctx is cancelled. A failed beat is logged and
-// retried on the next tick rather than killing the loop.
-func (h *heartbeater) Run(ctx context.Context) {
-	ticker := time.NewTicker(h.interval)
-	defer ticker.Stop()
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-ticker.C:
-			if err := h.beat(); err != nil {
-				slog.Warn("ecs-agent: heartbeat (re-register) failed", "err", err)
-			}
-		}
-	}
-}

cmd/ecs-agent/main.go

@@ -1,13 +1,6 @@
-// ecs-agent runs inside a Spinifex ECS container instance (a guest VM booted from
-// the ECS-AMI, with containerd baked in). It registers the host with the ECS
-// scheduler through the AWS gateway over TLS+SigV4 (never NATS), heartbeats by
-// re-registering, polls the gateway for task assignments, runs them through
-// containerd, and reports state back over the gateway.
-//
-// Static config (gateway URL, CA, region, cluster, seeded IAM creds, containerd
-// socket) is read from the cloud-init env file /etc/spinifex-ecs/agent.env
-// (KEY=value); real env vars override it. Host identity (account, instance, AZ)
-// comes from IMDS at boot.
+// Command ecs-agent runs inside a Spinifex ECS container instance; the
+// implementation is in agents/ecs/agent. This binary owns process lifecycle:
+// signal handling, startup and run failure logging, and the exit code.
 package main
 
 import (
@@ -17,13 +10,20 @@ import (
 	"os/signal"
 	"syscall"
 
-	_ "github.com/mulgadc/spinifex/internal/fipsboot"
+	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
+
+	ecsagent "github.com/mulgadc/spinifex/spinifex/agents/ecs/agent"
 )
 
-func main() {
-	cfg := loadConfig(defaultEnvFile)
+// version is the agent build version, reported in the register message.
+// Overridable via -ldflags "-X main.version=...".
+var version = "dev"
 
-	agent, err := New(cfg)
+func main() {
+	cfg := ecsagent.LoadConfig(ecsagent.DefaultEnvFile)
+	cfg.AgentVersion = version
+
+	agent, err := ecsagent.New(cfg)
 	if err != nil {
 		slog.Error("ecs-agent: startup failed", "err", err)
 		os.Exit(1)

cmd/ecs-agent/metadata.go

@@ -1,61 +0,0 @@
-package main
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"net/http"
-	"strings"
-
-	"github.com/aws/aws-sdk-go-v2/feature/ec2/imds"
-	"github.com/mulgadc/spinifex/internal/imdscreds"
-)
-
-// instanceMetadata is the IMDS-derived identity of the host the agent runs on.
-type instanceMetadata struct {
-	AccountID  string
-	InstanceID string
-	AZ         string
-}
-
-// fetchInstanceMetadata reads the instance-id, AZ and account-id from IMDSv2
-// via the SDK IMDS client. base is the IMDS root, e.g.
-// "http://169.254.169.254/latest".
-func fetchInstanceMetadata(client *http.Client, base string) (instanceMetadata, error) {
-	imdsClient := imdscreds.NewClient(client, base)
-	ctx := context.Background()
-
-	instanceID, err := getMetadata(ctx, imdsClient, "instance-id")
-	if err != nil {
-		return instanceMetadata{}, fmt.Errorf("instance-id: %w", err)
-	}
-	az, err := getMetadata(ctx, imdsClient, "placement/availability-zone")
-	if err != nil {
-		return instanceMetadata{}, fmt.Errorf("availability-zone: %w", err)
-	}
-
-	doc, err := imdsClient.GetInstanceIdentityDocument(ctx, &imds.GetInstanceIdentityDocumentInput{})
-	if err != nil {
-		return instanceMetadata{}, fmt.Errorf("identity document: %w", err)
-	}
-
-	return instanceMetadata{
-		AccountID:  doc.AccountID,
-		InstanceID: strings.TrimSpace(instanceID),
-		AZ:         strings.TrimSpace(az),
-	}, nil
-}
-
-// getMetadata reads a single meta-data path and returns its body as a string.
-func getMetadata(ctx context.Context, imdsClient *imds.Client, path string) (string, error) {
-	out, err := imdsClient.GetMetadata(ctx, &imds.GetMetadataInput{Path: path})
-	if err != nil {
-		return "", err
-	}
-	defer out.Content.Close()
-	body, err := io.ReadAll(out.Content)
-	if err != nil {
-		return "", err
-	}
-	return string(body), nil
-}

cmd/ecs-agent/metadata_test.go

@@ -1,82 +0,0 @@
-package main
-
-import (
-	"net/http"
-	"net/http/httptest"
-	"testing"
-)
-
-func metadataStub(t *testing.T, enforceV2 bool) *httptest.Server {
-	t.Helper()
-	mux := http.NewServeMux()
-	mux.HandleFunc("/latest/api/token", func(w http.ResponseWriter, r *http.Request) {
-		if r.Method != http.MethodPut {
-			w.WriteHeader(http.StatusMethodNotAllowed)
-			return
-		}
-		// Real IMDS echoes the requested TTL back as a response header; the SDK
-		// client parses it from there, not the body.
-		w.Header().Set("X-Aws-Ec2-Metadata-Token-Ttl-Seconds", "21600")
-		_, _ = w.Write([]byte("v2-token"))
-	})
-	guard := func(w http.ResponseWriter, r *http.Request) bool {
-		if enforceV2 && r.Header.Get("X-Aws-Ec2-Metadata-Token") != "v2-token" {
-			w.WriteHeader(http.StatusUnauthorized)
-			return false
-		}
-		return true
-	}
-	mux.HandleFunc("/latest/meta-data/instance-id", func(w http.ResponseWriter, r *http.Request) {
-		if guard(w, r) {
-			_, _ = w.Write([]byte("i-0abc123"))
-		}
-	})
-	mux.HandleFunc("/latest/meta-data/placement/availability-zone", func(w http.ResponseWriter, r *http.Request) {
-		if guard(w, r) {
-			_, _ = w.Write([]byte("us-east-1a"))
-		}
-	})
-	mux.HandleFunc("/latest/dynamic/instance-identity/document", func(w http.ResponseWriter, r *http.Request) {
-		if guard(w, r) {
-			_, _ = w.Write([]byte(`{"accountId":"123456789012","region":"us-east-1"}`))
-		}
-	})
-	srv := httptest.NewServer(mux)
-	t.Cleanup(srv.Close)
-	return srv
-}
-
-func TestFetchInstanceMetadata_OK(t *testing.T) {
-	srv := metadataStub(t, true)
-	got, err := fetchInstanceMetadata(srv.Client(), srv.URL+"/latest")
-	if err != nil {
-		t.Fatalf("fetch: %v", err)
-	}
-	if got.InstanceID != "i-0abc123" || got.AZ != "us-east-1a" || got.AccountID != "123456789012" {
-		t.Errorf("metadata mismatch: %+v", got)
-	}
-}
-
-func TestFetchInstanceMetadata_TokenRequired(t *testing.T) {
-	// Server returns 405 for non-PUT token; a GET-only client would 401 downstream.
-	srv := metadataStub(t, true)
-	if _, err := fetchInstanceMetadata(srv.Client(), srv.URL+"/latest"); err != nil {
-		t.Fatalf("v2 path should succeed: %v", err)
-	}
-}
-
-func TestFetchInstanceMetadata_BadDocument(t *testing.T) {
-	mux := http.NewServeMux()
-	mux.HandleFunc("/latest/api/token", func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("X-Aws-Ec2-Metadata-Token-Ttl-Seconds", "21600")
-		_, _ = w.Write([]byte("t"))
-	})
-	mux.HandleFunc("/latest/meta-data/instance-id", func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write([]byte("i-1")) })
-	mux.HandleFunc("/latest/meta-data/placement/availability-zone", func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write([]byte("z")) })
-	mux.HandleFunc("/latest/dynamic/instance-identity/document", func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write([]byte("not json")) })
-	srv := httptest.NewServer(mux)
-	t.Cleanup(srv.Close)
-	if _, err := fetchInstanceMetadata(srv.Client(), srv.URL+"/latest"); err == nil {
-		t.Fatal("expected parse error on bad identity document")
-	}
-}

cmd/ecs-agent/reconcile.go

@@ -1,110 +0,0 @@
-package main
-
-import (
-	"context"
-	"log/slog"
-
-	ctrruntime "github.com/mulgadc/spinifex/cmd/ecs-agent/runtime"
-	"github.com/mulgadc/spinifex/spinifex/handlers/ecs/bus"
-)
-
-// reconcile re-syncs the gateway with what this instance is actually running
-// after an agent restart. It lists the runtime's containers and, for each task
-// in this cluster, either re-adopts it (still running: re-register IAM
-// credentials, re-attach the exit-wait, refresh RUNNING) or reports it STOPPED
-// and clears its leftovers. The returned set seeds pollAssignments so the
-// gateway's re-delivered assignments for these tasks are acked but not re-run.
-//
-// Reporting the dead ones is the load-bearing half. The exit-wait is cancelled
-// when the agent shuts down, so a container that dies while the agent is down
-// has nobody to report its exit; the gateway holds the task RUNNING forever,
-// its service never replaces it, and the target never recovers.
-//
-// It is best-effort: a nil runner or a List error returns an empty set and the
-// agent falls back to its pre-reconcile behaviour (poll + run).
-func (a *Agent) reconcile(ctx context.Context) map[string]bool {
-	adopted := map[string]bool{}
-	if a.runner == nil {
-		return adopted
-	}
-	containers, err := a.runner.List(ctx)
-	if err != nil {
-		slog.Warn("ecs-agent: reconcile list failed", "err", err)
-		return adopted
-	}
-
-	// Group this cluster's containers back into their tasks, running or not. The
-	// Assign is reconstructed from labels — enough to re-register creds and tear
-	// down netns.
-	type task struct {
-		as      *bus.Assign
-		running []ctrruntime.Container
-		dead    []ctrruntime.Container
-	}
-	tasks := map[string]*task{}
-	for _, c := range containers {
-		if c.Labels[labelClusterName] != a.id.ClusterName {
-			continue
-		}
-		taskID := c.Labels[labelTaskID]
-		if taskID == "" {
-			continue
-		}
-		t := tasks[taskID]
-		if t == nil {
-			t = &task{as: &bus.Assign{
-				TaskID:        taskID,
-				ClusterName:   a.id.ClusterName,
-				CredID:        c.Labels[labelCredID],
-				TaskRoleARN:   c.Labels[labelTaskRoleARN],
-				ENIMacAddress: c.Labels[labelENIMac],
-			}}
-			tasks[taskID] = t
-		}
-		if c.Running {
-			t.running = append(t.running, c)
-		} else {
-			t.dead = append(t.dead, c)
-		}
-	}
-
-	for taskID, t := range tasks {
-		// A task with nothing running is over, whatever the gateway still believes.
-		// Mixed running/dead is left to the running path: the exit-wait re-attached
-		// below reports the individual container when it is reaped.
-		if len(t.running) == 0 {
-			a.reportStoppedTask(ctx, t.as, t.dead)
-			adopted[taskID] = true
-			continue
-		}
-
-		a.registerTaskCreds(t.as)
-		statuses := make([]bus.ContainerStatus, 0, len(t.running))
-		for _, c := range t.running {
-			name := c.Labels[labelContainerName]
-			go a.waitContainer(ctx, t.as, name, c.ID)
-			statuses = append(statuses, bus.ContainerStatus{Name: name, Status: bus.TaskStatusRunning, ContainerID: c.ID})
-		}
-		a.reportTaskState(t.as, bus.TaskStatusRunning, "", statuses)
-		adopted[taskID] = true
-		slog.Info("ecs-agent: re-adopted running task", "task", taskID, "containers", len(t.running))
-	}
-	return adopted
-}
-
-// reportStoppedTask clears a task's leftover containers and tells the gateway it
-// is STOPPED, so the scheduler stops counting a task this instance is not
-// running and its service can place a replacement.
-func (a *Agent) reportStoppedTask(ctx context.Context, as *bus.Assign, dead []ctrruntime.Container) {
-	statuses := make([]bus.ContainerStatus, 0, len(dead))
-	for _, c := range dead {
-		if err := a.runner.Remove(ctx, c.ID); err != nil {
-			slog.Warn("ecs-agent: reconcile remove failed", "task", as.TaskID, "container", c.ID, "err", err)
-		}
-		statuses = append(statuses, bus.ContainerStatus{
-			Name: c.Labels[labelContainerName], Status: bus.TaskStatusStopped, ContainerID: c.ID,
-		})
-	}
-	a.reportTaskState(as, bus.TaskStatusStopped, "Container exited while the agent was not running", statuses)
-	slog.Info("ecs-agent: reported stopped task", "task", as.TaskID, "containers", len(dead))
-}

cmd/ecs-agent/reconcile_test.go

@@ -1,250 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"slices"
-	"testing"
-	"time"
-
-	ctrruntime "github.com/mulgadc/spinifex/cmd/ecs-agent/runtime"
-	"github.com/mulgadc/spinifex/spinifex/handlers/ecs/bus"
-)
-
-const testTaskRole = "arn:aws:iam::111122223333:role/task"
-
-// adoptedContainer builds a runtime.Container as the reconciler would discover it,
-// stamping only the mulga.ecs.* labels that are non-empty.
-func adoptedContainer(taskID, name, cluster, credID, role, mac string, running bool) ctrruntime.Container {
-	labels := map[string]string{
-		labelTaskID:        taskID,
-		labelContainerName: name,
-		labelClusterName:   cluster,
-	}
-	if credID != "" {
-		labels[labelCredID] = credID
-	}
-	if role != "" {
-		labels[labelTaskRoleARN] = role
-	}
-	if mac != "" {
-		labels[labelENIMac] = mac
-	}
-	return ctrruntime.Container{ID: containerID(taskID, name), Labels: labels, Running: running}
-}
-
-func waitedFor(t *testing.T, rt *ctrruntime.FakePuller, id string) {
-	t.Helper()
-	deadline := time.After(time.Second)
-	for !slices.Contains(rt.Waits(), id) {
-		select {
-		case <-deadline:
-			t.Fatalf("exit-wait never re-attached for %s; waited=%v", id, rt.Waits())
-		case <-time.After(2 * time.Millisecond):
-		}
-	}
-}
-
-// A running, correctly-labeled container is re-adopted: its credentials are
-// re-registered, its RUNNING state refreshed, and its exit-wait re-attached.
-func TestReconcile_AdoptsRunningLabeledContainer(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{
-		WaitErr: errors.New("blocked"),
-		Containers: []ctrruntime.Container{
-			adoptedContainer("t-001", "web", "default", "t-001", testTaskRole, "52:54:00:de:ad:01", true),
-		},
-	}
-	a := newAgent(config{}, testIdentity(), cp, rt, rt, nil)
-	a.cred = newCredEndpoint(nil, "us-east-1", "https://gw", "", "127.0.0.1", 0, nil)
-
-	adopted := a.reconcile(context.Background())
-
-	if !adopted["t-001"] {
-		t.Fatalf("t-001 not adopted; got %v", adopted)
-	}
-	if got := a.cred.roles["t-001"]; got != testTaskRole {
-		t.Errorf("cred not re-registered: roles[t-001] = %q, want %q", got, testTaskRole)
-	}
-	if n := countStatus(cp.taskStates(), "t-001", bus.TaskStatusRunning); n != 1 {
-		t.Errorf("RUNNING reports for t-001 = %d, want 1", n)
-	}
-	waitedFor(t, rt, containerID("t-001", "web"))
-}
-
-// A task whose container died while the agent was down must be reported STOPPED,
-// not silently skipped. The exit-wait is cancelled on agent shutdown, so nothing
-// else ever reports that exit: skipping it leaves the gateway holding the task
-// RUNNING forever, its service never places a replacement, and the load
-// balancer target stays unhealthy with no path back.
-func TestReconcile_ReportsTaskWhoseContainerDied(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{
-		Containers: []ctrruntime.Container{
-			adoptedContainer("t-dead", "web", "default", "t-dead", testTaskRole, "52:54:00:de:ad:02", false),
-		},
-	}
-	a := newAgent(config{}, testIdentity(), cp, rt, rt, nil)
-	a.cred = newCredEndpoint(nil, "us-east-1", "https://gw", "", "127.0.0.1", 0, nil)
-
-	adopted := a.reconcile(context.Background())
-
-	if n := countStatus(cp.taskStates(), "t-dead", bus.TaskStatusStopped); n != 1 {
-		t.Errorf("STOPPED reports for t-dead = %d, want 1", n)
-	}
-	if n := countStatus(cp.taskStates(), "t-dead", bus.TaskStatusRunning); n != 0 {
-		t.Errorf("t-dead must not be reported RUNNING, got %d such reports", n)
-	}
-	// Seeded so a re-delivered assignment for the dead task is acked, not re-run.
-	if !adopted["t-dead"] {
-		t.Errorf("t-dead not seeded into the adopted set; got %v", adopted)
-	}
-	if want := containerID("t-dead", "web"); !slices.Contains(rt.Removed, want) {
-		t.Errorf("leftover container %s not removed; removed=%v", want, rt.Removed)
-	}
-}
-
-// A task with one live and one dead container is still running: the live half is
-// re-adopted and the re-attached exit-wait reports the dead one when it is
-// reaped, so reconcile must not declare the whole task STOPPED.
-func TestReconcile_PartiallyDeadTaskStaysRunning(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{
-		WaitErr: errors.New("blocked"),
-		Containers: []ctrruntime.Container{
-			adoptedContainer("t-mixed", "web", "default", "t-mixed", testTaskRole, "52:54:00:de:ad:03", true),
-			adoptedContainer("t-mixed", "sidecar", "default", "t-mixed", testTaskRole, "52:54:00:de:ad:03", false),
-		},
-	}
-	a := newAgent(config{}, testIdentity(), cp, rt, rt, nil)
-	a.cred = newCredEndpoint(nil, "us-east-1", "https://gw", "", "127.0.0.1", 0, nil)
-
-	a.reconcile(context.Background())
-
-	if n := countStatus(cp.taskStates(), "t-mixed", bus.TaskStatusRunning); n != 1 {
-		t.Errorf("RUNNING reports for t-mixed = %d, want 1", n)
-	}
-	if n := countStatus(cp.taskStates(), "t-mixed", bus.TaskStatusStopped); n != 0 {
-		t.Errorf("t-mixed must not be reported STOPPED while a container still runs, got %d", n)
-	}
-}
-
-// pollAssignments seeded with an adopted task acks its re-delivered assignment
-// but does not re-run it, while a genuinely new task still dispatches.
-func TestPollAssignments_SeededTaskNotRerun(t *testing.T) {
-	mk := func(id string) bus.Assign {
-		return bus.Assign{
-			AccountID: "123456789012", ClusterName: "default", InstanceID: "i-abc123", TaskID: id,
-			Containers: []bus.AssignContainer{{Name: "web", Image: "registry/web:1", Command: []string{"/bin/true"}}},
-		}
-	}
-	adopted, fresh := mk("t-001"), mk("t-002")
-	cp := &fakeCP{pollReplies: [][]bus.Assign{
-		{adopted, fresh},
-		{adopted, fresh},
-		nil,
-	}}
-	rt := &ctrruntime.FakePuller{WaitErr: errors.New("blocked")}
-	a := newAgent(config{PollInterval: 5 * time.Millisecond}, testIdentity(), cp, rt, rt, nil)
-
-	ctx, cancel := context.WithCancel(context.Background())
-	go a.pollAssignments(ctx, map[string]bool{"t-001": true})
-
-	deadline := time.After(time.Second)
-	for countStatus(cp.taskStates(), "t-002", bus.TaskStatusRunning) < 1 {
-		select {
-		case <-deadline:
-			t.Fatal("fresh task t-002 was never dispatched")
-		case <-time.After(2 * time.Millisecond):
-		}
-	}
-	time.Sleep(20 * time.Millisecond)
-	cancel()
-
-	if n := countStatus(cp.taskStates(), "t-001", bus.TaskStatusRunning); n != 0 {
-		t.Errorf("adopted task t-001 was re-run %d times, want 0", n)
-	}
-	if n := countStatus(cp.taskStates(), "t-002", bus.TaskStatusRunning); n != 1 {
-		t.Errorf("fresh task t-002 dispatched %d times, want 1", n)
-	}
-	var t1Acked bool
-	for _, ack := range cp.acks() {
-		for _, id := range ack {
-			if id == "t-001" {
-				t1Acked = true
-			}
-		}
-	}
-	if !t1Acked {
-		t.Errorf("adopted task t-001 was never acked; acks=%v", cp.acks())
-	}
-}
-
-// Containers belonging to another cluster are ignored entirely: this agent
-// speaks for its own cluster only, and must neither adopt nor report them.
-//
-// A stopped container of this cluster IS handled — see
-// TestReconcile_ReportsTaskWhoseContainerDied. It lands in the adopted set so
-// its re-delivered assignment is acked rather than re-run, after reconcile has
-// reported the task STOPPED.
-func TestReconcile_IgnoresOtherClusterContainers(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{
-		WaitErr: errors.New("blocked"),
-		Containers: []ctrruntime.Container{
-			adoptedContainer("t-other", "web", "other", "", "", "", true),
-			adoptedContainer("t-other-dead", "web", "other", "", "", "", false),
-			adoptedContainer("t-ok", "web", "default", "", "", "", true),
-		},
-	}
-	a := newAgent(config{}, testIdentity(), cp, rt, rt, nil)
-
-	adopted := a.reconcile(context.Background())
-
-	if len(adopted) != 1 || !adopted["t-ok"] {
-		t.Fatalf("adopted = %v, want only t-ok", adopted)
-	}
-	for _, id := range []string{"t-other", "t-other-dead"} {
-		if n := countStatus(cp.taskStates(), id, bus.TaskStatusStopped); n != 0 {
-			t.Errorf("reported %d STOPPED states for another cluster's task %s, want 0", n, id)
-		}
-	}
-}
-
-// A nil runner or a List error degrades to an empty set without panicking.
-func TestReconcile_DegradesGracefully(t *testing.T) {
-	noRunner := newAgent(config{}, testIdentity(), &fakeCP{}, nil, nil, nil)
-	if got := noRunner.reconcile(context.Background()); len(got) != 0 {
-		t.Errorf("nil runner: adopted = %v, want empty", got)
-	}
-
-	rt := &ctrruntime.FakePuller{ListErr: errors.New("boom")}
-	listErr := newAgent(config{}, testIdentity(), &fakeCP{}, rt, rt, nil)
-	if got := listErr.reconcile(context.Background()); len(got) != 0 {
-		t.Errorf("list error: adopted = %v, want empty", got)
-	}
-}
-
-// taskLabels emits the optional cred/role/MAC labels only when set.
-func TestTaskLabels_OmitsEmptyOptionalLabels(t *testing.T) {
-	full := taskLabels(&bus.Assign{
-		TaskID: "t1", ClusterName: "c", CredID: "x", TaskRoleARN: testTaskRole, ENIMacAddress: "mac",
-	}, "web")
-	for k, want := range map[string]string{
-		labelCredID: "x", labelTaskRoleARN: testTaskRole, labelENIMac: "mac",
-	} {
-		if full[k] != want {
-			t.Errorf("full labels[%q] = %q, want %q", k, full[k], want)
-		}
-	}
-
-	bare := taskLabels(&bus.Assign{TaskID: "t1", ClusterName: "c"}, "web")
-	if len(bare) != 3 {
-		t.Errorf("bare labels = %v, want only taskID/containerName/clusterName", bare)
-	}
-	for _, k := range []string{labelCredID, labelTaskRoleARN, labelENIMac} {
-		if _, ok := bare[k]; ok {
-			t.Errorf("bare labels unexpectedly carry %q", k)
-		}
-	}
-}

cmd/ecs-agent/registration.go

@@ -1,39 +0,0 @@
-package main
-
-import (
-	"fmt"
-
-	"github.com/mulgadc/spinifex/spinifex/handlers/ecs/bus"
-)
-
-// identity is the container instance's stable identity, assembled at boot from
-// IMDS (account, instance, AZ) and config (cluster). It is the join key the
-// scheduler uses to track this instance.
-type identity struct {
-	AccountID    string
-	ClusterName  string
-	InstanceID   string
-	AZ           string
-	Hostname     string
-	Capacity     bus.InstanceCapacity
-	AgentVersion string
-}
-
-// registrar registers the host as a container instance through the gateway.
-type registrar struct {
-	cp controlPlane
-	id identity
-}
-
-func newRegistrar(cp controlPlane, id identity) *registrar {
-	return &registrar{cp: cp, id: id}
-}
-
-// Register calls the gateway's RegisterContainerInstance. The scheduler records
-// (or refreshes) the container instance on receipt.
-func (r *registrar) Register() error {
-	if err := r.cp.Register(r.id); err != nil {
-		return fmt.Errorf("register instance %s: %w", r.id.InstanceID, err)
-	}
-	return nil
-}

cmd/ecs-agent/registration_test.go

@@ -1,195 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"sync"
-	"testing"
-	"time"
-
-	handlers_ecs "github.com/mulgadc/spinifex/spinifex/handlers/ecs"
-	"github.com/mulgadc/spinifex/spinifex/handlers/ecs/bus"
-)
-
-// fakeCP is a test double for the gateway control-plane. It records registers,
-// task-state reports and GPU reports, and replays a scripted queue of poll
-// responses.
-type fakeCP struct {
-	mu sync.Mutex
-
-	registers    int
-	states       []bus.TaskState
-	gpuReports   []gpuReport
-	pollAcks     [][]string
-	pollStopAcks [][]string
-	pollReplies  [][]bus.Assign
-	stopReplies  [][]bus.StopDirective
-	pollCalls    int
-
-	registerErr bool
-	submitErr   bool
-}
-
-// gpuReport is one recorded ReportTaskGPU call.
-type gpuReport struct {
-	cluster    string
-	task       string
-	containers []handlers_ecs.ContainerGPUReport
-}
-
-var _ controlPlane = (*fakeCP)(nil)
-
-func (f *fakeCP) Register(_ identity) error {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	if f.registerErr {
-		return errors.New("register boom")
-	}
-	f.registers++
-	return nil
-}
-
-func (f *fakeCP) SubmitTaskState(st bus.TaskState) error {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	if f.submitErr {
-		return errors.New("submit boom")
-	}
-	f.states = append(f.states, st)
-	return nil
-}
-
-func (f *fakeCP) PollAssignments(_, _ string, ackAssigns, ackStops []string) ([]bus.Assign, []bus.StopDirective, error) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.pollAcks = append(f.pollAcks, append([]string(nil), ackAssigns...))
-	f.pollStopAcks = append(f.pollStopAcks, append([]string(nil), ackStops...))
-	var out []bus.Assign
-	if f.pollCalls < len(f.pollReplies) {
-		out = f.pollReplies[f.pollCalls]
-	}
-	var stops []bus.StopDirective
-	if f.pollCalls < len(f.stopReplies) {
-		stops = f.stopReplies[f.pollCalls]
-	}
-	f.pollCalls++
-	return out, stops, nil
-}
-
-func (f *fakeCP) ReportTaskGPU(cluster, task string, containers []handlers_ecs.ContainerGPUReport) error {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.gpuReports = append(f.gpuReports, gpuReport{cluster: cluster, task: task, containers: containers})
-	return nil
-}
-
-func (f *fakeCP) gpuReportsFor(taskID string) []gpuReport {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	var out []gpuReport
-	for _, r := range f.gpuReports {
-		if r.task == taskID {
-			out = append(out, r)
-		}
-	}
-	return out
-}
-
-func (f *fakeCP) registerCount() int {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	return f.registers
-}
-
-func (f *fakeCP) taskStates() []bus.TaskState {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	return append([]bus.TaskState(nil), f.states...)
-}
-
-func (f *fakeCP) acks() [][]string {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	return append([][]string(nil), f.pollAcks...)
-}
-
-func (f *fakeCP) stopAcks() [][]string {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	return append([][]string(nil), f.pollStopAcks...)
-}
-
-func testIdentity() identity {
-	return identity{
-		AccountID:    "123456789012",
-		ClusterName:  "default",
-		InstanceID:   "i-abc123",
-		AZ:           "us-east-1a",
-		Hostname:     "ecs-host",
-		Capacity:     bus.InstanceCapacity{CPU: 2048, MemoryMiB: 4096},
-		AgentVersion: "test",
-	}
-}
-
-// testIdentityWithGPUs is testIdentity seeded with discovered GPU UUIDs, so
-// newAgent's ledger has real devices to pin from.
-func testIdentityWithGPUs(uuids ...string) identity {
-	id := testIdentity()
-	id.Capacity.GPU = len(uuids)
-	id.Capacity.GPUIDs = uuids
-	return id
-}
-
-func TestRegistrar_Register(t *testing.T) {
-	cp := &fakeCP{}
-	if err := newRegistrar(cp, testIdentity()).Register(); err != nil {
-		t.Fatalf("Register: %v", err)
-	}
-	if cp.registerCount() != 1 {
-		t.Errorf("registers = %d, want 1", cp.registerCount())
-	}
-}
-
-func TestRegistrar_RegisterError(t *testing.T) {
-	cp := &fakeCP{registerErr: true}
-	if err := newRegistrar(cp, testIdentity()).Register(); err == nil {
-		t.Fatal("expected register error")
-	}
-}
-
-func TestHeartbeater_Beat(t *testing.T) {
-	cp := &fakeCP{}
-	if err := newHeartbeater(cp, testIdentity(), time.Second).beat(); err != nil {
-		t.Fatalf("beat: %v", err)
-	}
-	if cp.registerCount() != 1 {
-		t.Errorf("beat should re-register once, got %d", cp.registerCount())
-	}
-}
-
-func TestHeartbeater_DefaultInterval(t *testing.T) {
-	h := newHeartbeater(&fakeCP{}, testIdentity(), 0)
-	if h.interval != defaultHeartbeat {
-		t.Errorf("interval = %v, want default", h.interval)
-	}
-}
-
-func TestHeartbeater_RunStopsOnContext(t *testing.T) {
-	cp := &fakeCP{}
-	h := newHeartbeater(cp, testIdentity(), 5*time.Millisecond)
-	ctx, cancel := context.WithCancel(context.Background())
-
-	done := make(chan struct{})
-	go func() { h.Run(ctx); close(done) }()
-
-	time.Sleep(25 * time.Millisecond)
-	cancel()
-	select {
-	case <-done:
-	case <-time.After(time.Second):
-		t.Fatal("Run did not stop on context cancel")
-	}
-	if cp.registerCount() == 0 {
-		t.Error("expected at least one re-register before cancel")
-	}
-}

cmd/ecs-agent/runtime/containerd_run.go

@@ -1,172 +0,0 @@
-package runtime
-
-import (
-	"context"
-	"fmt"
-	"sort"
-
-	containerd "github.com/containerd/containerd/v2/client"
-	"github.com/containerd/containerd/v2/pkg/cdi"
-	"github.com/containerd/containerd/v2/pkg/cio"
-	"github.com/containerd/containerd/v2/pkg/namespaces"
-	"github.com/containerd/containerd/v2/pkg/oci"
-	specs "github.com/opencontainers/runtime-spec/specs-go"
-)
-
-// cdiVendorGPU is the NVIDIA CDI vendor/class prefix for whole-GPU devices, per
-// the NVIDIA CDI naming convention (nvidia.com/gpu=<uuid>).
-const cdiVendorGPU = "nvidia.com/gpu"
-
-// cdiDeviceNames maps a container's pinned GPU device UUIDs to CDI device
-// names. Empty input (non-GPU container) returns nil so no CDI opt is added.
-func cdiDeviceNames(uuids []string) []string {
-	if len(uuids) == 0 {
-		return nil
-	}
-	names := make([]string, len(uuids))
-	for i, id := range uuids {
-		names[i] = cdiVendorGPU + "=" + id
-	}
-	return names
-}
-
-// cdiSpecOpts returns the oci.SpecOpts needed to inject gpuIDs (via
-// containerd's CDI machinery) as devices into a container's OCI spec. It
-// returns nil for a non-GPU container so Run adds nothing to the opts list.
-func cdiSpecOpts(gpuIDs []string) []oci.SpecOpts {
-	devices := cdiDeviceNames(gpuIDs)
-	if len(devices) == 0 {
-		return nil
-	}
-	return []oci.SpecOpts{cdi.WithCDIDevices(devices...)}
-}
-
-var _ Runner = (*containerdPuller)(nil)
-
-// Run creates a container from an already-pulled image and starts its task. The
-// container joins the host network namespace (bridge/CNI task networking is a
-// later sprint) and carries spec.Labels for the reboot reconciler. id must be
-// unique within the "ecs" namespace.
-func (p *containerdPuller) Run(ctx context.Context, id string, spec RunSpec) (string, error) {
-	ctx = namespaces.WithNamespace(ctx, ecsNamespace)
-
-	ref, err := normalizeRef(spec.Image)
-	if err != nil {
-		return "", err
-	}
-	image, err := p.client.GetImage(ctx, ref)
-	if err != nil {
-		return "", fmt.Errorf("get image %s: %w", ref, err)
-	}
-
-	specOpts := []oci.SpecOpts{
-		oci.WithImageConfig(image),
-		oci.WithHostHostsFile,
-		oci.WithHostResolvconf,
-	}
-	if spec.NetnsPath != "" {
-		// awsvpc: join the task ENI netns built by the agent.
-		specOpts = append(specOpts, oci.WithLinuxNamespace(specs.LinuxNamespace{
-			Type: specs.NetworkNamespace,
-			Path: spec.NetnsPath,
-		}))
-	} else {
-		// bridge/host: share the VM (host) netns.
-		specOpts = append(specOpts, oci.WithHostNamespace(specs.NetworkNamespace))
-	}
-	if len(spec.Command) > 0 {
-		specOpts = append(specOpts, oci.WithProcessArgs(spec.Command...))
-	}
-	if len(spec.Env) > 0 {
-		specOpts = append(specOpts, oci.WithEnv(envSlice(spec.Env)))
-	}
-	specOpts = append(specOpts, cdiSpecOpts(spec.GPUIDs)...)
-
-	container, err := p.client.NewContainer(ctx, id,
-		containerd.WithNewSnapshot(id+"-snapshot", image),
-		containerd.WithNewSpec(specOpts...),
-		containerd.WithContainerLabels(spec.Labels),
-	)
-	if err != nil {
-		return "", fmt.Errorf("create container %s: %w", id, err)
-	}
-
-	task, err := container.NewTask(ctx, cio.NullIO)
-	if err != nil {
-		_ = container.Delete(ctx, containerd.WithSnapshotCleanup)
-		return "", fmt.Errorf("create task %s: %w", id, err)
-	}
-	if err := task.Start(ctx); err != nil {
-		_, _ = task.Delete(ctx)
-		_ = container.Delete(ctx, containerd.WithSnapshotCleanup)
-		return "", fmt.Errorf("start task %s: %w", id, err)
-	}
-	return id, nil
-}
-
-// Wait blocks until the container's task exits and returns its exit code.
-func (p *containerdPuller) Wait(ctx context.Context, containerID string) (RunStatus, error) {
-	ctx = namespaces.WithNamespace(ctx, ecsNamespace)
-	container, err := p.client.LoadContainer(ctx, containerID)
-	if err != nil {
-		return RunStatus{}, fmt.Errorf("load container %s: %w", containerID, err)
-	}
-	task, err := container.Task(ctx, nil)
-	if err != nil {
-		return RunStatus{}, fmt.Errorf("attach task %s: %w", containerID, err)
-	}
-	statusC, err := task.Wait(ctx)
-	if err != nil {
-		return RunStatus{}, fmt.Errorf("wait task %s: %w", containerID, err)
-	}
-	status := <-statusC
-	code, _, err := status.Result()
-	return RunStatus{ExitCode: int(code)}, err
-}
-
-// List enumerates every container in the ecs namespace with its labels and
-// whether its task is running, so the agent can re-adopt live containers after a
-// restart. Per-container label/task errors are treated as "not running" rather
-// than failing the whole list.
-func (p *containerdPuller) List(ctx context.Context) ([]Container, error) {
-	ctx = namespaces.WithNamespace(ctx, ecsNamespace)
-	containers, err := p.client.Containers(ctx)
-	if err != nil {
-		return nil, fmt.Errorf("list containers: %w", err)
-	}
-	out := make([]Container, 0, len(containers))
-	for _, c := range containers {
-		labels, _ := c.Labels(ctx)
-		running := false
-		if task, terr := c.Task(ctx, nil); terr == nil {
-			if status, serr := task.Status(ctx); serr == nil {
-				running = status.Status == containerd.Running
-			}
-		}
-		out = append(out, Container{ID: c.ID(), Labels: labels, Running: running})
-	}
-	return out, nil
-}
-
-// Remove kills and deletes the container's task, then the container + snapshot.
-func (p *containerdPuller) Remove(ctx context.Context, containerID string) error {
-	ctx = namespaces.WithNamespace(ctx, ecsNamespace)
-	container, err := p.client.LoadContainer(ctx, containerID)
-	if err != nil {
-		return nil //nolint:nilerr // load failure means the container is already gone
-	}
-	if task, terr := container.Task(ctx, nil); terr == nil {
-		_, _ = task.Delete(ctx, containerd.WithProcessKill)
-	}
-	return container.Delete(ctx, containerd.WithSnapshotCleanup)
-}
-
-// envSlice renders an env map as sorted "K=V" entries for deterministic specs.
-func envSlice(env map[string]string) []string {
-	out := make([]string, 0, len(env))
-	for k, v := range env {
-		out = append(out, k+"="+v)
-	}
-	sort.Strings(out)
-	return out
-}

cmd/ecs-agent/runtime/containerd_run_test.go

@@ -1,47 +0,0 @@
-package runtime
-
-import (
-	"reflect"
-	"testing"
-)
-
-// cdiDeviceNames maps a container's pinned GPU UUIDs to CDI device names
-// (nvidia.com/gpu=<uuid>); Run wires the result into oci.WithCDIDevices when
-// non-empty, so this is the injection logic's unit-testable core.
-func TestCDIDeviceNames(t *testing.T) {
-	cases := []struct {
-		name  string
-		uuids []string
-		want  []string
-	}{
-		{name: "empty", uuids: nil, want: nil},
-		{name: "single", uuids: []string{"GPU-aaaaaaaa-1111-2222-3333-444444444444"},
-			want: []string{"nvidia.com/gpu=GPU-aaaaaaaa-1111-2222-3333-444444444444"}},
-		{name: "multiple preserves order", uuids: []string{"GPU-aaa", "GPU-bbb"},
-			want: []string{"nvidia.com/gpu=GPU-aaa", "nvidia.com/gpu=GPU-bbb"}},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			got := cdiDeviceNames(tc.uuids)
-			if !reflect.DeepEqual(got, tc.want) {
-				t.Errorf("cdiDeviceNames(%v) = %v, want %v", tc.uuids, got, tc.want)
-			}
-		})
-	}
-}
-
-// TestCDISpecOpts_Wiring confirms Run's specOpts list picks up exactly one CDI
-// opt when GPUIDs is non-empty, and none for a non-GPU container — the wiring
-// Run relies on (a live oci.Spec is needed to unit test the opt's effect).
-func TestCDISpecOpts_Wiring(t *testing.T) {
-	if opts := cdiSpecOpts(nil); len(opts) != 0 {
-		t.Errorf("non-GPU container: want no spec opts, got %d", len(opts))
-	}
-	opts := cdiSpecOpts([]string{"GPU-aaa", "GPU-bbb"})
-	if len(opts) != 1 {
-		t.Fatalf("GPU container: want exactly one CDI spec opt, got %d", len(opts))
-	}
-	if opts[0] == nil {
-		t.Error("GPU container: spec opt is nil")
-	}
-}

cmd/ecs-agent/runtime/runtime.go

@@ -1,88 +0,0 @@
-// Package runtime is the ecs-agent's container-runtime seam. The agent pulls
-// task images and (from Sprint 4e) runs containers through an ImagePuller; the
-// real implementation drives containerd, but the interface lets tests and the
-// scheduler-only build run against a fake.
-package runtime
-
-import "context"
-
-// PullSpec describes one image to pull.
-type PullSpec struct {
-	// Ref is the full image reference, e.g.
-	// "123456789012.dkr.ecr.us-east-1.spinifex.internal/app:latest".
-	Ref string
-}
-
-// Image identifies a pulled image in the runtime's content store.
-type Image struct {
-	Ref    string
-	Digest string
-	Size   int64
-}
-
-// Resolver supplies registry credentials for a given image reference. The
-// ecs-agent backs this with ECR GetAuthorizationToken (see ecrresolver.go).
-type Resolver interface {
-	// Authorize returns the username, password and registry endpoint to use for
-	// ref. An empty user/pass means anonymous pull.
-	Authorize(ctx context.Context, ref string) (user, pass, endpoint string, err error)
-}
-
-// ImagePuller pulls images into the local runtime. Close releases the runtime
-// client connection.
-type ImagePuller interface {
-	Pull(ctx context.Context, spec PullSpec, r Resolver) (Image, error)
-	Close() error
-}
-
-// RunSpec describes a single container the agent must create and start. v1 runs
-// the container in the host network namespace (bridge/CNI task networking lands
-// in a later sprint); Labels carry the mulga.ecs.* task identity for the reboot
-// reconciler.
-type RunSpec struct {
-	Image   string
-	Command []string
-	Env     map[string]string
-	Labels  map[string]string
-	// NetnsPath, when set, joins the container to a pre-built network namespace
-	// (awsvpc task ENI). Empty keeps the container in the host (VM) netns —
-	// bridge/host mode behaviour.
-	NetnsPath string
-	// GPU is the whole-GPU count requested for this container.
-	GPU int
-	// GPUIDs are the ledger-pinned device UUIDs assigned to this container, one
-	// per GPU requested. Empty for non-GPU containers or if pinning fell short.
-	// The runner injects these as CDI devices into the OCI spec.
-	GPUIDs []string
-}
-
-// RunStatus is a finished container's outcome.
-type RunStatus struct {
-	ExitCode int
-}
-
-// Container is a container the runtime already knows about, discovered by List.
-// Labels carry the mulga.ecs.* task identity so the agent can re-adopt running
-// containers after a restart; Running reports whether its task is live.
-type Container struct {
-	ID      string
-	Labels  map[string]string
-	Running bool
-}
-
-// Runner creates and starts containers from already-pulled images. id is a
-// caller-unique container ID; Wait blocks until the container exits; Remove
-// tears down the container + its task; List enumerates known containers so the
-// reboot reconciler can re-adopt the ones still running.
-type Runner interface {
-	Run(ctx context.Context, id string, spec RunSpec) (containerID string, err error)
-	Wait(ctx context.Context, containerID string) (RunStatus, error)
-	Remove(ctx context.Context, containerID string) error
-	List(ctx context.Context) ([]Container, error)
-}
-
-// Runtime is the full container runtime the ecs-agent drives: pull + run.
-type Runtime interface {
-	ImagePuller
-	Runner
-}

cmd/ecs-agent/runtime/runtime_fake.go

@@ -1,125 +0,0 @@
-package runtime
-
-import (
-	"context"
-	"fmt"
-	"sync"
-)
-
-// FakePuller is an in-memory ImagePuller for tests and the scheduler-only build.
-// It records pull requests and replays a programmed result or error.
-type FakePuller struct {
-	mu     sync.Mutex
-	Pulls  []PullSpec
-	Authzd []string
-	Result Image
-	Err    error
-	Closed bool
-	OnPull func(PullSpec) (Image, error)
-
-	// Run bookkeeping.
-	Runs     []RunSpec
-	RunErr   error
-	WaitCode int
-	WaitErr  error
-	Waited   []string
-	Removed  []string
-	OnRun    func(string, RunSpec) (string, error)
-
-	// List bookkeeping: Containers is replayed by List; ListErr forces a failure;
-	// Listed records that List was called.
-	Containers []Container
-	ListErr    error
-	Listed     bool
-}
-
-var (
-	_ ImagePuller = (*FakePuller)(nil)
-	_ Runner      = (*FakePuller)(nil)
-)
-
-// Pull records the spec, exercises the resolver, and returns the programmed
-// result. If OnPull is set it takes precedence over Result/Err.
-func (f *FakePuller) Pull(ctx context.Context, spec PullSpec, r Resolver) (Image, error) {
-	f.mu.Lock()
-	f.Pulls = append(f.Pulls, spec)
-	f.mu.Unlock()
-
-	if r != nil {
-		user, _, _, err := r.Authorize(ctx, spec.Ref)
-		if err != nil {
-			return Image{}, fmt.Errorf("authorize %s: %w", spec.Ref, err)
-		}
-		f.mu.Lock()
-		f.Authzd = append(f.Authzd, user)
-		f.mu.Unlock()
-	}
-
-	if f.OnPull != nil {
-		return f.OnPull(spec)
-	}
-	if f.Err != nil {
-		return Image{}, f.Err
-	}
-	res := f.Result
-	if res.Ref == "" {
-		res.Ref = spec.Ref
-	}
-	return res, nil
-}
-
-// Close marks the puller closed.
-func (f *FakePuller) Close() error {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.Closed = true
-	return nil
-}
-
-// Run records the spec and returns id (or the programmed result/error).
-func (f *FakePuller) Run(_ context.Context, id string, spec RunSpec) (string, error) {
-	f.mu.Lock()
-	f.Runs = append(f.Runs, spec)
-	f.mu.Unlock()
-	if f.OnRun != nil {
-		return f.OnRun(id, spec)
-	}
-	if f.RunErr != nil {
-		return "", f.RunErr
-	}
-	return id, nil
-}
-
-// Wait records the container ID and returns the programmed exit code/error.
-func (f *FakePuller) Wait(_ context.Context, containerID string) (RunStatus, error) {
-	f.mu.Lock()
-	f.Waited = append(f.Waited, containerID)
-	f.mu.Unlock()
-	return RunStatus{ExitCode: f.WaitCode}, f.WaitErr
-}
-
-// Remove records the container ID.
-func (f *FakePuller) Remove(_ context.Context, containerID string) error {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.Removed = append(f.Removed, containerID)
-	return nil
-}
-
-// Waits returns a copy of the container IDs passed to Wait, for assertions.
-func (f *FakePuller) Waits() []string {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	return append([]string(nil), f.Waited...)
-}
-
-// List replays the programmed container set (or error).
-func (f *FakePuller) List(_ context.Context) ([]Container, error) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.Listed = true
-	if f.ListErr != nil {
-		return nil, f.ListErr
-	}
-	return f.Containers, nil
-}

cmd/ecs-agent/taskrun.go

@@ -1,340 +0,0 @@
-package main
-
-import (
-	"context"
-	"fmt"
-	"log/slog"
-	"maps"
-	"time"
-
-	ctrruntime "github.com/mulgadc/spinifex/cmd/ecs-agent/runtime"
-	handlers_ecs "github.com/mulgadc/spinifex/spinifex/handlers/ecs"
-	"github.com/mulgadc/spinifex/spinifex/handlers/ecs/bus"
-)
-
-// pollAssignments drains the instance's assignment inbox on a ticker until ctx is
-// cancelled. Each assign is dispatched to runTask exactly once; the taskIDs seen
-// on a poll are acked on the next poll so the gateway can drop them — a crash
-// before ack re-delivers (at-least-once), matching ACS. A failed poll is logged
-// and retried on the next tick rather than killing the loop. dispatched is seeded
-// by the startup reconcile with tasks already adopted from running containers, so
-// their re-delivered assignments are acked but not re-run.
-func (a *Agent) pollAssignments(ctx context.Context, dispatched map[string]bool) {
-	ticker := time.NewTicker(a.cfg.PollInterval)
-	defer ticker.Stop()
-
-	stopping := map[string]bool{}
-	var ackAssigns, ackStops []string
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-ticker.C:
-			assigns, stops, err := a.cp.PollAssignments(a.id.ClusterName, a.id.InstanceID, ackAssigns, ackStops)
-			if err != nil {
-				slog.Warn("ecs-agent: poll assignments failed", "err", err)
-				continue
-			}
-			// Dispatch stops first so a task stopped in the same poll it was assigned
-			// is never started.
-			ackStops = ackStops[:0]
-			for i := range stops {
-				sd := stops[i]
-				if !stopping[sd.TaskID] {
-					stopping[sd.TaskID] = true
-					slog.Info("ecs-agent: task stop requested", "task", sd.TaskID, "reason", sd.Reason)
-					go a.stopTask(ctx, sd)
-				}
-				ackStops = append(ackStops, sd.TaskID)
-			}
-			ackAssigns = ackAssigns[:0]
-			for i := range assigns {
-				as := assigns[i]
-				if !dispatched[as.TaskID] && !stopping[as.TaskID] {
-					dispatched[as.TaskID] = true
-					slog.Info("ecs-agent: task assigned", "task", as.TaskID, "containers", len(as.Containers))
-					go a.runTask(ctx, &as)
-				}
-				ackAssigns = append(ackAssigns, as.TaskID)
-			}
-		}
-	}
-}
-
-// stopTask reaps a task's containers on a control-plane stop directive: it lists
-// the runtime's containers, removes the ones labeled with this task (kill +
-// delete, releasing host ports/netns), then reports the task STOPPED with the
-// directive's reason. Idempotent — a task with no live containers still reports
-// STOPPED so the scheduler releases its capacity.
-func (a *Agent) stopTask(ctx context.Context, sd bus.StopDirective) {
-	if a.runner == nil {
-		return
-	}
-	containers, err := a.runner.List(ctx)
-	if err != nil {
-		slog.Warn("ecs-agent: stop list failed", "task", sd.TaskID, "err", err)
-		return
-	}
-	statuses := make([]bus.ContainerStatus, 0)
-	for _, c := range containers {
-		if c.Labels[labelTaskID] != sd.TaskID {
-			continue
-		}
-		if rerr := a.runner.Remove(ctx, c.ID); rerr != nil {
-			slog.Warn("ecs-agent: stop remove failed", "task", sd.TaskID, "container", c.ID, "err", rerr)
-		}
-		statuses = append(statuses, bus.ContainerStatus{
-			Name: c.Labels[labelContainerName], Status: bus.TaskStatusStopped, ContainerID: c.ID,
-		})
-	}
-	reason := sd.Reason
-	if reason == "" {
-		reason = "Task stopped"
-	}
-	a.reportTaskState(&bus.Assign{TaskID: sd.TaskID}, bus.TaskStatusStopped, reason, statuses)
-	slog.Info("ecs-agent: task reaped", "task", sd.TaskID, "containers", len(statuses))
-}
-
-// runTask pulls each container image, starts the containers, and reports task
-// state on the bus. A missing runtime or any per-container failure reports the
-// task STOPPED with a reason; success reports RUNNING and waits for exit.
-func (a *Agent) runTask(ctx context.Context, as *bus.Assign) {
-	if a.puller == nil || a.runner == nil {
-		a.reportTaskState(as, bus.TaskStatusStopped, "containerd unavailable on agent", nil)
-		return
-	}
-
-	// awsvpc: build the task netns from the hot-plugged ENI before any container.
-	netnsPath, err := a.setupTaskNetns(as)
-	if err != nil {
-		slog.Error("ecs-agent: task netns setup failed", "task", as.TaskID, "err", err)
-		a.reportTaskState(as, bus.TaskStatusStopped, "network setup failed: "+err.Error(), nil)
-		return
-	}
-
-	credID := a.registerTaskCreds(as)
-	resolver := a.pullResolver(as)
-
-	statuses := make([]bus.ContainerStatus, 0, len(as.Containers))
-	for _, c := range as.Containers {
-		if _, err := a.puller.Pull(ctx, ctrruntime.PullSpec{Ref: c.Image}, resolver); err != nil {
-			slog.Error("ecs-agent: pull failed", "task", as.TaskID, "image", c.Image, "err", err)
-			a.teardownTaskNetns(as)
-			a.reportTaskState(as, bus.TaskStatusStopped, "image pull failed: "+err.Error(), statuses)
-			return
-		}
-
-		cid := containerID(as.TaskID, c.Name)
-		gpuIDs := a.pinContainerGPUs(as.TaskID, c.Name, c.GPU)
-		spec := ctrruntime.RunSpec{
-			Image:     c.Image,
-			Command:   c.Command,
-			Env:       withCredEnv(c.Environment, credID),
-			Labels:    taskLabels(as, c.Name),
-			NetnsPath: netnsPath,
-			GPU:       c.GPU,
-			GPUIDs:    gpuIDs,
-		}
-		id, err := a.runner.Run(ctx, cid, spec)
-		if err != nil {
-			slog.Error("ecs-agent: run failed", "task", as.TaskID, "container", c.Name, "err", err)
-			a.teardownTaskNetns(as)
-			a.reportTaskState(as, bus.TaskStatusStopped, "container start failed: "+err.Error(), statuses)
-			return
-		}
-		statuses = append(statuses, bus.ContainerStatus{
-			Name: c.Name, Status: bus.TaskStatusRunning, ContainerID: id, GPUIDs: gpuIDs,
-		})
-		go a.waitContainer(ctx, as, c.Name, id)
-	}
-
-	a.reportTaskState(as, bus.TaskStatusRunning, "", statuses)
-	slog.Info("ecs-agent: task running", "task", as.TaskID, "containers", len(statuses))
-}
-
-// waitContainer blocks until a container exits, then reports the task STOPPED
-// with the exit code. v1 stops the whole task when its first container exits.
-func (a *Agent) waitContainer(ctx context.Context, as *bus.Assign, name, containerID string) {
-	status, err := a.runner.Wait(ctx, containerID)
-	if err != nil {
-		slog.Warn("ecs-agent: wait container failed", "task", as.TaskID, "container", name, "err", err)
-		return
-	}
-	exit := status.ExitCode
-	a.teardownTaskNetns(as)
-	statuses := []bus.ContainerStatus{{Name: name, Status: bus.TaskStatusStopped, ContainerID: containerID, ExitCode: &exit}}
-	a.reportTaskState(as, bus.TaskStatusStopped, fmt.Sprintf("container %s exited (%d)", name, exit), statuses)
-	slog.Info("ecs-agent: task stopped", "task", as.TaskID, "container", name, "exitCode", exit)
-}
-
-// setupTaskNetns builds the awsvpc task netns from the hot-plugged ENI. Bridge/
-// host tasks (no ENI MAC) and a nil controller are no-ops returning an empty path.
-func (a *Agent) setupTaskNetns(as *bus.Assign) (string, error) {
-	if as.ENIMacAddress == "" || a.netns == nil {
-		return "", nil
-	}
-	return a.netns.Setup(as.TaskID, as.ENIMacAddress)
-}
-
-// teardownTaskNetns releases the task's IAM credential registration, then removes
-// the awsvpc task netns (the latter is a no-op for bridge/host tasks). It runs at
-// every task-stop path so credentials never outlive the task that owns them.
-func (a *Agent) teardownTaskNetns(as *bus.Assign) {
-	if a.cred != nil {
-		a.cred.Deregister(taskCredID(as))
-	}
-	if as.ENIMacAddress == "" || a.netns == nil {
-		return
-	}
-	if err := a.netns.Teardown(as.TaskID); err != nil {
-		slog.Warn("ecs-agent: task netns teardown", "task", as.TaskID, "err", err)
-	}
-}
-
-// pullResolver returns the ECR resolver used for a task's image pulls. When the
-// assign carries an execution role, it authorizes pulls as that role (assumed
-// over the gateway); an empty role or a nil credential endpoint (unit tests)
-// falls back to the instance-role resolver, so a pull is never worse off.
-func (a *Agent) pullResolver(as *bus.Assign) ctrruntime.Resolver {
-	if as.ExecutionRoleARN == "" || a.cred == nil {
-		return a.resolver
-	}
-	prov := a.cred.AssumeProvider(as.ExecutionRoleARN, sessionName(as.TaskID))
-	return newLazyECRResolver(prov, a.cfg.Region, a.cfg.GatewayURL, a.cfg.GatewayCA)
-}
-
-// registerTaskCreds registers the task's credID -> role mapping with the
-// credential endpoint and returns the credID (empty when the task has no role).
-func (a *Agent) registerTaskCreds(as *bus.Assign) string {
-	credID := taskCredID(as)
-	if credID == "" || a.cred == nil {
-		return credID
-	}
-	a.cred.Register(credID, as.TaskRoleARN)
-	return credID
-}
-
-// taskCredID is the credential ID a task's containers fetch credentials under:
-// the scheduler-assigned CredID, falling back to the taskID. Empty when the task
-// carries no IAM role.
-func taskCredID(as *bus.Assign) string {
-	if as.TaskRoleARN == "" {
-		return ""
-	}
-	if as.CredID != "" {
-		return as.CredID
-	}
-	return as.TaskID
-}
-
-// withCredEnv returns env with AWS_CONTAINER_CREDENTIALS_RELATIVE_URI set for
-// credID, copying the map so the assign's container env is left untouched. A
-// blank credID (no task role) returns env unchanged.
-func withCredEnv(env map[string]string, credID string) map[string]string {
-	if credID == "" {
-		return env
-	}
-	out := make(map[string]string, len(env)+1)
-	maps.Copy(out, env)
-	out["AWS_CONTAINER_CREDENTIALS_RELATIVE_URI"] = credRelativeURI(credID)
-	return out
-}
-
-// pinContainerGPUs reserves n device UUIDs for a container from the local
-// ledger, before the container is started so the runner can inject them as
-// CDI devices. A short ledger (fewer free devices than requested, e.g.
-// discovery found none) is logged and treated as best-effort: the container
-// still runs without pinned UUIDs (and without GPU access) rather than
-// failing the task.
-func (a *Agent) pinContainerGPUs(taskID, containerName string, n int) []string {
-	if n <= 0 || a.gpu == nil {
-		return nil
-	}
-	uuids, err := a.gpu.Pin(gpuKey(taskID, containerName), n)
-	if err != nil {
-		slog.Warn("ecs-agent: gpu pin short", "task", taskID, "container", containerName, "err", err)
-	}
-	return uuids
-}
-
-// reportTaskState reports a task transition through the gateway's
-// SubmitTaskStateChange action, then (RUNNING with pinned GPUs) reports the
-// per-container device UUIDs, and (STOPPED) releases them back to the ledger.
-func (a *Agent) reportTaskState(as *bus.Assign, status, reason string, containers []bus.ContainerStatus) {
-	if a.cp == nil {
-		return
-	}
-	msg := bus.TaskState{
-		AccountID:   a.id.AccountID,
-		ClusterName: a.id.ClusterName,
-		InstanceID:  a.id.InstanceID,
-		TaskID:      as.TaskID,
-		LastStatus:  status,
-		Containers:  containers,
-		Reason:      reason,
-		ReportedAt:  time.Now().UTC(),
-	}
-	if err := a.cp.SubmitTaskState(msg); err != nil {
-		slog.Error("ecs-agent: report task-state failed", "task", as.TaskID, "err", err)
-	}
-	a.reportTaskGPUs(as.TaskID, containers)
-	if status == bus.TaskStatusStopped && a.gpu != nil {
-		a.gpu.ReleaseTask(as.TaskID)
-	}
-}
-
-// reportTaskGPUs sends the control plane the pinned device UUIDs for any
-// container in the report that has them, so DescribeTasks can surface gpuIds.
-// A no-op when nothing was pinned (the common non-GPU-task case).
-func (a *Agent) reportTaskGPUs(taskID string, containers []bus.ContainerStatus) {
-	reports := make([]handlers_ecs.ContainerGPUReport, 0, len(containers))
-	for _, c := range containers {
-		if len(c.GPUIDs) > 0 {
-			reports = append(reports, handlers_ecs.ContainerGPUReport{Name: c.Name, GPUIDs: c.GPUIDs})
-		}
-	}
-	if len(reports) == 0 {
-		return
-	}
-	if err := a.cp.ReportTaskGPU(a.id.ClusterName, taskID, reports); err != nil {
-		slog.Error("ecs-agent: report task-gpu failed", "task", taskID, "err", err)
-	}
-}
-
-// containerID composes a containerd-valid container ID from a task + container.
-func containerID(taskID, name string) string {
-	return fmt.Sprintf("%s-%s", taskID, name)
-}
-
-// mulga.ecs.* label keys stamped on every container. The reboot reconciler reads
-// them back to re-associate running containers with their task on restart; the
-// cred/role/MAC labels make a container self-describing enough to re-register its
-// credentials and tear down its netns without the original assignment.
-const (
-	labelTaskID        = "mulga.ecs.taskID"
-	labelContainerName = "mulga.ecs.containerName"
-	labelClusterName   = "mulga.ecs.clusterName"
-	labelCredID        = "mulga.ecs.credID"
-	labelTaskRoleARN   = "mulga.ecs.taskRoleArn"
-	labelENIMac        = "mulga.ecs.eniMac"
-)
-
-// taskLabels are the mulga.ecs.* labels stamped on a container. The cred/role/MAC
-// labels are omitted when empty so a container carries only what it needs.
-func taskLabels(as *bus.Assign, name string) map[string]string {
-	labels := map[string]string{
-		labelTaskID:        as.TaskID,
-		labelContainerName: name,
-		labelClusterName:   as.ClusterName,
-	}
-	if credID := taskCredID(as); credID != "" {
-		labels[labelCredID] = credID
-	}
-	if as.TaskRoleARN != "" {
-		labels[labelTaskRoleARN] = as.TaskRoleARN
-	}
-	if as.ENIMacAddress != "" {
-		labels[labelENIMac] = as.ENIMacAddress
-	}
-	return labels
-}

cmd/ecs-agent/taskrun_test.go

@@ -1,557 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"testing"
-	"time"
-
-	ctrruntime "github.com/mulgadc/spinifex/cmd/ecs-agent/runtime"
-	"github.com/mulgadc/spinifex/spinifex/handlers/ecs/bus"
-)
-
-func testAssign() *bus.Assign {
-	return &bus.Assign{
-		AccountID:   "123456789012",
-		ClusterName: "default",
-		InstanceID:  "i-abc123",
-		TaskID:      "t-001",
-		Containers: []bus.AssignContainer{
-			{Name: "web", Image: "registry/web:1", Command: []string{"/bin/true"},
-				Environment: map[string]string{"FOO": "bar"}},
-		},
-	}
-}
-
-func newRunAgent(cp controlPlane, rt *ctrruntime.FakePuller) *Agent {
-	return newAgent(config{}, testIdentity(), cp, rt, rt, nil)
-}
-
-// runTask with no runtime reports the task STOPPED instead of crashing.
-func TestRunTask_NoRuntimeReportsStopped(t *testing.T) {
-	cp := &fakeCP{}
-	a := newAgent(config{}, testIdentity(), cp, nil, nil, nil)
-	a.runTask(context.Background(), testAssign())
-
-	st := cp.taskStates()
-	if len(st) != 1 || st[0].LastStatus != bus.TaskStatusStopped {
-		t.Fatalf("want one STOPPED state, got %+v", st)
-	}
-	if st[0].Reason == "" {
-		t.Error("STOPPED state missing reason")
-	}
-}
-
-// Happy path: pull + run reports RUNNING with the container ID; Wait blocking
-// (forced error) means no STOPPED overwrite, so we can assert the RUNNING frame.
-func TestRunTask_PullRunReportsRunning(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{WaitErr: errors.New("blocked")}
-	a := newRunAgent(cp, rt)
-	as := testAssign()
-	a.runTask(context.Background(), as)
-
-	if len(rt.Pulls) != 1 || rt.Pulls[0].Ref != "registry/web:1" {
-		t.Fatalf("expected one pull of registry/web:1, got %+v", rt.Pulls)
-	}
-	if len(rt.Runs) != 1 || rt.Runs[0].Image != "registry/web:1" {
-		t.Fatalf("expected one run, got %+v", rt.Runs)
-	}
-	if rt.Runs[0].Labels["mulga.ecs.taskID"] != "t-001" {
-		t.Errorf("missing task label: %+v", rt.Runs[0].Labels)
-	}
-
-	st := cp.taskStates()
-	if len(st) == 0 || st[len(st)-1].LastStatus != bus.TaskStatusRunning {
-		t.Fatalf("want RUNNING final state, got %+v", st)
-	}
-	if len(st[len(st)-1].Containers) != 1 || st[len(st)-1].Containers[0].ContainerID != "t-001-web" {
-		t.Errorf("RUNNING state container wrong: %+v", st[len(st)-1].Containers)
-	}
-}
-
-// TestRunTask_GPUCarriedToRunSpec verifies that the AssignContainer's GPU count
-// reaches the runtime RunSpec unchanged; a
-// container with no GPU request keeps RunSpec.GPU at zero (regression).
-func TestRunTask_GPUCarriedToRunSpec(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{WaitErr: errors.New("blocked")}
-	a := newRunAgent(cp, rt)
-	as := testAssign()
-	as.Containers = append(as.Containers, bus.AssignContainer{
-		Name: "trainer", Image: "registry/trainer:1", GPU: 2,
-	})
-	a.runTask(context.Background(), as)
-
-	if len(rt.Runs) != 2 {
-		t.Fatalf("expected two runs, got %+v", rt.Runs)
-	}
-	if rt.Runs[0].GPU != 0 {
-		t.Errorf("web container: want GPU=0, got %d", rt.Runs[0].GPU)
-	}
-	if rt.Runs[1].GPU != 2 {
-		t.Errorf("trainer container: want GPU=2, got %d", rt.Runs[1].GPU)
-	}
-}
-
-// TestRunTask_GPUPinsAndReportsUUIDs covers C3: a container's GPU request is
-// pinned from the agent's local ledger, carried on the RUNNING report's
-// ContainerStatus, and forwarded to the control plane via ReportTaskGPU.
-func TestRunTask_GPUPinsAndReportsUUIDs(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{WaitErr: errors.New("blocked")}
-	a := newAgent(config{}, testIdentityWithGPUs("GPU-aaa", "GPU-bbb"), cp, rt, rt, nil)
-	as := testAssign()
-	as.Containers = append(as.Containers, bus.AssignContainer{
-		Name: "trainer", Image: "registry/trainer:1", GPU: 1,
-	})
-	a.runTask(context.Background(), as)
-
-	st := cp.taskStates()
-	if len(st) == 0 || st[len(st)-1].LastStatus != bus.TaskStatusRunning {
-		t.Fatalf("want RUNNING final state, got %+v", st)
-	}
-	last := st[len(st)-1]
-	var trainer *bus.ContainerStatus
-	for i := range last.Containers {
-		if last.Containers[i].Name == "trainer" {
-			trainer = &last.Containers[i]
-		}
-	}
-	if trainer == nil || len(trainer.GPUIDs) != 1 {
-		t.Fatalf("trainer container missing pinned GPU UUID: %+v", last.Containers)
-	}
-	if trainer.GPUIDs[0] != "GPU-aaa" && trainer.GPUIDs[0] != "GPU-bbb" {
-		t.Errorf("unexpected pinned UUID %q", trainer.GPUIDs[0])
-	}
-
-	reports := cp.gpuReportsFor(as.TaskID)
-	if len(reports) != 1 {
-		t.Fatalf("want one ReportTaskGPU call, got %d", len(reports))
-	}
-	if reports[0].cluster != as.ClusterName {
-		t.Errorf("report cluster = %q, want %q", reports[0].cluster, as.ClusterName)
-	}
-	if len(reports[0].containers) != 1 || reports[0].containers[0].Name != "trainer" {
-		t.Errorf("report containers = %+v, want one trainer entry", reports[0].containers)
-	}
-}
-
-// TestRunTask_GPUIDsReachRunSpec covers C4: the ledger's pinned UUIDs for a
-// container reach RunSpec.GPUIDs (not just the RunSpec.GPU count), so the
-// runner can inject them as CDI devices; a non-GPU container's RunSpec
-// carries no GPUIDs.
-func TestRunTask_GPUIDsReachRunSpec(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{WaitErr: errors.New("blocked")}
-	a := newAgent(config{}, testIdentityWithGPUs("GPU-aaa", "GPU-bbb"), cp, rt, rt, nil)
-	as := testAssign()
-	as.Containers = append(as.Containers, bus.AssignContainer{
-		Name: "trainer", Image: "registry/trainer:1", GPU: 1,
-	})
-	a.runTask(context.Background(), as)
-
-	if len(rt.Runs) != 2 {
-		t.Fatalf("expected two runs, got %+v", rt.Runs)
-	}
-	if len(rt.Runs[0].GPUIDs) != 0 {
-		t.Errorf("web container: want no GPUIDs, got %+v", rt.Runs[0].GPUIDs)
-	}
-	trainer := rt.Runs[1]
-	if len(trainer.GPUIDs) != 1 {
-		t.Fatalf("trainer container: want one pinned GPUID, got %+v", trainer.GPUIDs)
-	}
-	if trainer.GPUIDs[0] != "GPU-aaa" && trainer.GPUIDs[0] != "GPU-bbb" {
-		t.Errorf("unexpected pinned UUID %q", trainer.GPUIDs[0])
-	}
-}
-
-// A container with no GPU request never triggers a ReportTaskGPU call.
-func TestRunTask_NoGPUSkipsReport(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{WaitErr: errors.New("blocked")}
-	a := newRunAgent(cp, rt)
-	as := testAssign()
-	a.runTask(context.Background(), as)
-
-	if reports := cp.gpuReportsFor(as.TaskID); len(reports) != 0 {
-		t.Errorf("want no GPU report for a non-GPU task, got %+v", reports)
-	}
-}
-
-// A GPU request exceeding the ledger's free devices (discovery found none, or
-// fewer than requested) is best-effort: the container still runs, it just
-// carries no pinned UUIDs and so no CDI devices are injected.
-func TestRunTask_GPUShortLedgerStillRuns(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{WaitErr: errors.New("blocked")}
-	a := newRunAgent(cp, rt) // testIdentity() has no discovered GPU UUIDs
-	as := testAssign()
-	as.Containers = append(as.Containers, bus.AssignContainer{
-		Name: "trainer", Image: "registry/trainer:1", GPU: 2,
-	})
-	a.runTask(context.Background(), as)
-
-	if len(rt.Runs) != 2 {
-		t.Fatalf("expected both containers to run despite the short ledger, got %+v", rt.Runs)
-	}
-	if reports := cp.gpuReportsFor(as.TaskID); len(reports) != 0 {
-		t.Errorf("want no GPU report when nothing was pinned, got %+v", reports)
-	}
-}
-
-// stopTask releases the task's pinned GPU UUIDs back to the ledger so a later
-// task on the same instance can reuse them.
-func TestStopTask_ReleasesGPUsBackToLedger(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{Containers: []ctrruntime.Container{
-		{ID: "t-001-trainer", Running: true, Labels: map[string]string{
-			"mulga.ecs.taskID": "t-001", "mulga.ecs.containerName": "trainer",
-		}},
-	}}
-	a := newAgent(config{}, testIdentityWithGPUs("GPU-aaa"), cp, rt, rt, nil)
-	if _, err := a.gpu.Pin(gpuKey("t-001", "trainer"), 1); err != nil {
-		t.Fatalf("seed pin: %v", err)
-	}
-	if len(a.gpu.free) != 0 {
-		t.Fatalf("setup: want ledger fully pinned, free = %v", a.gpu.free)
-	}
-
-	a.stopTask(context.Background(), bus.StopDirective{TaskID: "t-001", Reason: "bye"})
-
-	if len(a.gpu.free) != 1 {
-		t.Errorf("want the GPU released back to the ledger, free = %v", a.gpu.free)
-	}
-}
-
-// A pull failure reports STOPPED and never starts the container.
-func TestRunTask_PullFailureReportsStopped(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{Err: errors.New("pull denied")}
-	a := newRunAgent(cp, rt)
-	a.runTask(context.Background(), testAssign())
-
-	if len(rt.Runs) != 0 {
-		t.Errorf("container should not run after pull failure, got %+v", rt.Runs)
-	}
-	st := cp.taskStates()
-	if len(st) != 1 || st[0].LastStatus != bus.TaskStatusStopped {
-		t.Fatalf("want STOPPED, got %+v", st)
-	}
-}
-
-// A run failure reports STOPPED.
-func TestRunTask_RunFailureReportsStopped(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{RunErr: errors.New("start boom")}
-	a := newRunAgent(cp, rt)
-	a.runTask(context.Background(), testAssign())
-
-	st := cp.taskStates()
-	if len(st) != 1 || st[0].LastStatus != bus.TaskStatusStopped {
-		t.Fatalf("want STOPPED, got %+v", st)
-	}
-}
-
-// On container exit, waitContainer reports STOPPED with the exit code.
-func TestRunTask_ExitReportsStoppedWithCode(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{WaitCode: 7}
-	a := newRunAgent(cp, rt)
-	a.runTask(context.Background(), testAssign())
-
-	deadline := time.After(time.Second)
-	for {
-		st := cp.taskStates()
-		if len(st) > 0 && st[len(st)-1].LastStatus == bus.TaskStatusStopped {
-			last := st[len(st)-1]
-			if len(last.Containers) != 1 || last.Containers[0].ExitCode == nil || *last.Containers[0].ExitCode != 7 {
-				t.Fatalf("want exit code 7, got %+v", last.Containers)
-			}
-			return
-		}
-		select {
-		case <-deadline:
-			t.Fatalf("no STOPPED state after exit; got %+v", cp.taskStates())
-		case <-time.After(2 * time.Millisecond):
-		}
-	}
-}
-
-// pollAssignments dispatches each assign once and acks it on the next poll.
-func TestPollAssignments_DispatchesOnceAndAcks(t *testing.T) {
-	as := testAssign()
-	cp := &fakeCP{pollReplies: [][]bus.Assign{
-		{*as}, // poll 1: one pending assign
-		{*as}, // poll 2: still present (not yet acked when poll 2 was issued)
-		nil,   // poll 3: gateway dropped it after the ack
-	}}
-	rt := &ctrruntime.FakePuller{WaitErr: errors.New("blocked")}
-	a := newAgent(config{PollInterval: 5 * time.Millisecond}, testIdentity(), cp, rt, rt, nil)
-
-	ctx, cancel := context.WithCancel(context.Background())
-	go a.pollAssignments(ctx, map[string]bool{})
-
-	// runTask reports RUNNING through the (mutex-guarded) control plane. With the
-	// assign returned on two consecutive polls, dedup means exactly one dispatch →
-	// exactly one RUNNING report.
-	deadline := time.After(time.Second)
-	for {
-		if running := countStatus(cp.taskStates(), as.TaskID, bus.TaskStatusRunning); running >= 1 {
-			break
-		}
-		select {
-		case <-deadline:
-			t.Fatal("assign was never dispatched (no RUNNING report)")
-		case <-time.After(2 * time.Millisecond):
-		}
-	}
-	time.Sleep(20 * time.Millisecond)
-	cancel()
-
-	if running := countStatus(cp.taskStates(), as.TaskID, bus.TaskStatusRunning); running != 1 {
-		t.Errorf("task dispatched %d times, want exactly 1 (dedup on taskID)", running)
-	}
-	// The taskID must appear in a later poll's ack list.
-	acked := false
-	for _, ack := range cp.acks() {
-		for _, id := range ack {
-			if id == as.TaskID {
-				acked = true
-			}
-		}
-	}
-	if !acked {
-		t.Errorf("task %s was never acked; acks=%v", as.TaskID, cp.acks())
-	}
-}
-
-// stopTask reaps the task's labeled containers and reports STOPPED with the
-// directive reason and container status.
-func TestStopTask_ReapsLabeledContainersAndReportsStopped(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{Containers: []ctrruntime.Container{
-		{ID: "t-001-web", Running: true, Labels: map[string]string{
-			"mulga.ecs.taskID": "t-001", "mulga.ecs.containerName": "web",
-		}},
-		{ID: "t-999-other", Running: true, Labels: map[string]string{
-			"mulga.ecs.taskID": "t-999", "mulga.ecs.containerName": "web",
-		}},
-	}}
-	a := newRunAgent(cp, rt)
-
-	a.stopTask(context.Background(), bus.StopDirective{TaskID: "t-001", Reason: "bye"})
-
-	if len(rt.Removed) != 1 || rt.Removed[0] != "t-001-web" {
-		t.Fatalf("want only t-001-web removed, got %+v", rt.Removed)
-	}
-	st := cp.taskStates()
-	if len(st) != 1 || st[0].LastStatus != bus.TaskStatusStopped {
-		t.Fatalf("want one STOPPED report, got %+v", st)
-	}
-	if st[0].Reason != "bye" {
-		t.Errorf("want reason %q, got %q", "bye", st[0].Reason)
-	}
-	if len(st[0].Containers) != 1 || st[0].Containers[0].Status != bus.TaskStatusStopped {
-		t.Errorf("want one STOPPED container, got %+v", st[0].Containers)
-	}
-}
-
-// A stop for a task with no live containers still reports STOPPED so the
-// scheduler releases its capacity.
-func TestStopTask_NoContainersStillReportsStopped(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{}
-	a := newRunAgent(cp, rt)
-
-	a.stopTask(context.Background(), bus.StopDirective{TaskID: "t-001", Reason: "gone"})
-
-	if len(rt.Removed) != 0 {
-		t.Errorf("nothing to remove, got %+v", rt.Removed)
-	}
-	st := cp.taskStates()
-	if len(st) != 1 || st[0].LastStatus != bus.TaskStatusStopped {
-		t.Fatalf("want one STOPPED report, got %+v", st)
-	}
-}
-
-// A stop delivered by poll is dispatched once, acked in the stop-ack list, and
-// suppresses a same-poll assign for the same task.
-func TestPollAssignments_StopReapsAndSuppressesAssign(t *testing.T) {
-	as := testAssign()
-	cp := &fakeCP{
-		pollReplies: [][]bus.Assign{{*as}, {*as}, nil},
-		stopReplies: [][]bus.StopDirective{{{TaskID: as.TaskID, Reason: "bye"}}},
-	}
-	rt := &ctrruntime.FakePuller{Containers: []ctrruntime.Container{
-		{ID: "t-001-web", Running: true, Labels: map[string]string{"mulga.ecs.taskID": "t-001"}},
-	}}
-	a := newAgent(config{PollInterval: 5 * time.Millisecond}, testIdentity(), cp, rt, rt, nil)
-
-	ctx, cancel := context.WithCancel(context.Background())
-	go a.pollAssignments(ctx, map[string]bool{})
-
-	deadline := time.After(time.Second)
-	for {
-		if stopped := countStatus(cp.taskStates(), as.TaskID, bus.TaskStatusStopped); stopped >= 1 {
-			break
-		}
-		select {
-		case <-deadline:
-			t.Fatalf("stop never reaped; states=%+v", cp.taskStates())
-		case <-time.After(2 * time.Millisecond):
-		}
-	}
-	time.Sleep(20 * time.Millisecond)
-	cancel()
-
-	// The assign for the stopping task must never have started a container.
-	if len(rt.Runs) != 0 {
-		t.Errorf("assign for a stopping task should not run, got %+v", rt.Runs)
-	}
-	if running := countStatus(cp.taskStates(), as.TaskID, bus.TaskStatusRunning); running != 0 {
-		t.Errorf("stopping task should never report RUNNING, got %d", running)
-	}
-	acked := false
-	for _, ack := range cp.stopAcks() {
-		for _, id := range ack {
-			if id == as.TaskID {
-				acked = true
-			}
-		}
-	}
-	if !acked {
-		t.Errorf("stop %s was never acked; stopAcks=%v", as.TaskID, cp.stopAcks())
-	}
-}
-
-// stopTask with no runtime is a no-op: nothing to reap, no state reported.
-func TestStopTask_NilRunnerNoOp(t *testing.T) {
-	cp := &fakeCP{}
-	a := newAgent(config{}, testIdentity(), cp, nil, nil, nil)
-	a.stopTask(context.Background(), bus.StopDirective{TaskID: "t-001", Reason: "x"})
-	if len(cp.taskStates()) != 0 {
-		t.Fatalf("nil runner should report no state, got %+v", cp.taskStates())
-	}
-}
-
-// A List failure aborts the reap without reporting a (false) STOPPED state.
-func TestStopTask_ListErrorNoReport(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{ListErr: errors.New("list boom")}
-	a := newRunAgent(cp, rt)
-	a.stopTask(context.Background(), bus.StopDirective{TaskID: "t-001", Reason: "x"})
-	if len(cp.taskStates()) != 0 {
-		t.Fatalf("list error should report no state, got %+v", cp.taskStates())
-	}
-}
-
-// A directive with no reason reaps the matching container and reports STOPPED with
-// the default reason.
-func TestStopTask_EmptyReasonReapsWithDefault(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{Containers: []ctrruntime.Container{{
-		ID: "t-001-web",
-		Labels: map[string]string{
-			"mulga.ecs.taskID": "t-001", "mulga.ecs.containerName": "web",
-		},
-	}}}
-	a := newRunAgent(cp, rt)
-	a.stopTask(context.Background(), bus.StopDirective{TaskID: "t-001"})
-
-	if len(rt.Removed) != 1 || rt.Removed[0] != "t-001-web" {
-		t.Fatalf("want container t-001-web reaped, got %+v", rt.Removed)
-	}
-	st := cp.taskStates()
-	if len(st) != 1 || st[0].LastStatus != bus.TaskStatusStopped {
-		t.Fatalf("want one STOPPED report, got %+v", st)
-	}
-	if st[0].Reason != "Task stopped" {
-		t.Errorf("want default reason %q, got %q", "Task stopped", st[0].Reason)
-	}
-}
-
-func countStatus(states []bus.TaskState, taskID, status string) int {
-	n := 0
-	for _, st := range states {
-		if st.TaskID == taskID && st.LastStatus == status {
-			n++
-		}
-	}
-	return n
-}
-
-// awsvpc: an assign carrying an ENI MAC builds the task netns and passes its
-// path to the container RunSpec.
-func TestRunTask_AwsvpcBuildsNetns(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{WaitErr: errors.New("blocked")}
-	a := newRunAgent(cp, rt)
-	f := &fakeNetRunner{linkOut: linkWithENI}
-	a.netns = newTestNetns(f)
-
-	as := testAssign()
-	as.ENIMacAddress = "52:54:00:de:ad:01"
-	a.runTask(context.Background(), as)
-
-	if !f.sawAny("ip netns add ecs-t-001") {
-		t.Fatalf("expected task netns build, got %v", f.joined())
-	}
-	if len(rt.Runs) != 1 || rt.Runs[0].NetnsPath != netnsPathFor("t-001") {
-		t.Fatalf("want NetnsPath %q on RunSpec, got %+v", netnsPathFor("t-001"), rt.Runs)
-	}
-}
-
-// bridge/host: no ENI MAC means no netns is built and the container runs in the
-// host (VM) netns (empty NetnsPath).
-func TestRunTask_NoMacSkipsNetns(t *testing.T) {
-	cp := &fakeCP{}
-	rt := &ctrruntime.FakePuller{WaitErr: errors.New("blocked")}
-	a := newRunAgent(cp, rt)
-	f := &fakeNetRunner{linkOut: linkWithENI}
-	a.netns = newTestNetns(f)
-
-	a.runTask(context.Background(), testAssign())
-
-	if len(f.joined()) != 0 {
-		t.Fatalf("expected no netns commands, got %v", f.joined())
-	}
-	if len(rt.Runs) != 1 || rt.Runs[0].NetnsPath != "" {
-		t.Fatalf("want empty NetnsPath, got %+v", rt.Runs)
-	}
-}
-
-func TestContainerID(t *testing.T) {
-	if got := containerID("t-1", "web"); got != "t-1-web" {
-		t.Errorf("containerID = %q, want t-1-web", got)
-	}
-}
-
-// sentinelResolver is an identity-comparable Resolver for pullResolver tests.
-type sentinelResolver struct{}
-
-func (sentinelResolver) Authorize(context.Context, string) (string, string, string, error) {
-	return "", "", "", nil
-}
-
-// TestPullResolver verifies that an assign with no execution role (or no
-// credential endpoint) uses the instance resolver; with both, a distinct
-// exec-role resolver is built.
-func TestPullResolver(t *testing.T) {
-	fake := sentinelResolver{}
-	a := newAgent(config{Region: "us-east-1"}, testIdentity(), &fakeCP{}, nil, nil, fake)
-
-	if got := a.pullResolver(&bus.Assign{TaskID: "t1"}); got != fake {
-		t.Fatalf("no execution role: want instance resolver fallback")
-	}
-	execAssign := &bus.Assign{TaskID: "t1", ExecutionRoleARN: "arn:aws:iam::1:role/e"}
-	if got := a.pullResolver(execAssign); got != fake {
-		t.Fatalf("nil cred endpoint: want instance resolver fallback")
-	}
-
-	a.cred = &credEndpoint{}
-	got := a.pullResolver(execAssign)
-	if got == nil || got == fake {
-		t.Fatalf("execution role + cred endpoint: want distinct exec-role resolver, got %v", got)
-	}
-}

cmd/eks-gateway-fetch/main.go

@@ -1,196 +1,43 @@
 // eks-gateway-fetch runs inside the EKS K3s control-plane VM and fetches a
-// control-plane resource from the host through the AWS gateway, instead of
-// dialing core NATS directly. It is the read-side companion to
-// eks-gateway-publish.
-//
-// It SigV4-signs (service "eks") an HTTPS GET to the gateway, retrying with
-// backoff until the gateway returns 2xx or the attempt budget is exhausted (so
-// a degraded link surfaces as a non-zero exit), then emits the staged add-ons
-// as tab-separated lines the on-VM addon-sync shell agent consumes without a
-// JSON parser:
-//
-//	<addonName>\t<addonVersion>\t<serviceAccountRoleArn>\t<base64(configurationValues)>
-//
-// The configuration values are base64-encoded so embedded tabs/newlines cannot
-// break the line framing.
+// control-plane resource from the host through the AWS gateway, writing it to
+// stdout as TSV; the implementation is in agents/eks/gatewayfetch.
 //
 // Usage:
 //
 //	eks-gateway-fetch -resource addons   # GET /clusters/{cluster}/internal-addons/{accountId}
 //	eks-gateway-fetch -resource recovery -instance-id i-… # GET /clusters/{cluster}/internal-recovery/{accountId}/{instanceId}
 //
-// The recovery resource returns a single epoch\taction\tsnapshot line the on-VM
-// k3s-recovery agent applies before k3s starts (etcd cluster-reset / wipe-rejoin).
-//
 // Flags default to environment variables seeded by cloud-init:
 // EKS_GATEWAY_URL, EKS_GATEWAY_CA, EKS_ACCESS_KEY, EKS_SECRET_KEY, EKS_REGION,
 // EKS_ACCOUNT_ID, EKS_CLUSTER_NAME, EKS_INSTANCE_ID.
 package main
 
 import (
-	"bufio"
-	"encoding/base64"
-	"encoding/json"
+	"context"
 	"flag"
-	"fmt"
-	"io"
 	"log/slog"
 	"os"
-	"time"
 
-	"github.com/mulgadc/spinifex/internal/eksgw"
+	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
 
-	_ "github.com/mulgadc/spinifex/internal/fipsboot"
-)
-
-// stagedAddon mirrors the gateway's StagedAddonManifest wire shape; duplicated
-// here to keep this tiny VM binary free of the handler package's dependency
-// graph.
-type stagedAddon struct {
-	AddonName             string `json:"addonName"`
-	AddonVersion          string `json:"addonVersion"`
-	ServiceAccountRoleArn string `json:"serviceAccountRoleArn"`
-	ConfigurationValues   string `json:"configurationValues"`
-}
-
-type internalAddonsResponse struct {
-	Addons []stagedAddon `json:"addons"`
-}
-
-const (
-	maxAttempts = 30
-	retryDelay  = 5 * time.Second
+	"github.com/mulgadc/spinifex/spinifex/agents/eks/gatewayfetch"
 )
 
 func main() {
-	var (
-		gatewayURL  string
-		gatewayCA   string
-		accessKey   string
-		secretKey   string
-		region      string
-		accountID   string
-		clusterName string
-		resource    string
-		instanceID  string
-	)
-
-	flag.StringVar(&gatewayURL, "gateway", os.Getenv("EKS_GATEWAY_URL"), "Gateway URL (e.g. https://10.15.8.1:9999)")
-	flag.StringVar(&gatewayCA, "gateway-ca", os.Getenv("EKS_GATEWAY_CA"), "Path to gateway TLS CA PEM (optional; falls back to system trust)")
-	flag.StringVar(&accessKey, "access-key", os.Getenv("EKS_ACCESS_KEY"), "AWS access key ID")
-	flag.StringVar(&secretKey, "secret-key", os.Getenv("EKS_SECRET_KEY"), "AWS secret access key")
-	flag.StringVar(&region, "region", os.Getenv("EKS_REGION"), "AWS region for SigV4 signing")
-	flag.StringVar(&accountID, "account-id", os.Getenv("EKS_ACCOUNT_ID"), "Cluster account ID")
-	flag.StringVar(&clusterName, "cluster", os.Getenv("EKS_CLUSTER_NAME"), "Cluster name")
-	flag.StringVar(&instanceID, "instance-id", os.Getenv("EKS_INSTANCE_ID"), "This member's EC2 instance ID (recovery resource)")
-	flag.StringVar(&resource, "resource", "addons", "Resource to fetch: addons | recovery")
+	cfg := gatewayfetch.Config{Out: os.Stdout}
+	flag.StringVar(&cfg.GatewayURL, "gateway", os.Getenv("EKS_GATEWAY_URL"), "Gateway URL (e.g. https://10.15.8.1:9999)")
+	flag.StringVar(&cfg.GatewayCA, "gateway-ca", os.Getenv("EKS_GATEWAY_CA"), "Path to gateway TLS CA PEM (optional; falls back to system trust)")
+	flag.StringVar(&cfg.AccessKey, "access-key", os.Getenv("EKS_ACCESS_KEY"), "AWS access key ID")
+	flag.StringVar(&cfg.SecretKey, "secret-key", os.Getenv("EKS_SECRET_KEY"), "AWS secret access key")
+	flag.StringVar(&cfg.Region, "region", os.Getenv("EKS_REGION"), "AWS region for SigV4 signing")
+	flag.StringVar(&cfg.AccountID, "account-id", os.Getenv("EKS_ACCOUNT_ID"), "Cluster account ID")
+	flag.StringVar(&cfg.ClusterName, "cluster", os.Getenv("EKS_CLUSTER_NAME"), "Cluster name")
+	flag.StringVar(&cfg.InstanceID, "instance-id", os.Getenv("EKS_INSTANCE_ID"), "This member's EC2 instance ID (recovery resource)")
+	flag.StringVar(&cfg.Resource, "resource", "addons", "Resource to fetch: addons | recovery")
 	flag.Parse()
 
-	switch {
-	case accountID == "":
-		fatal("--account-id is required (or set EKS_ACCOUNT_ID)")
-	case clusterName == "":
-		fatal("--cluster is required (or set EKS_CLUSTER_NAME)")
-	case resource != "addons" && resource != "recovery":
-		fatal("--resource must be addons or recovery")
-	case resource == "recovery" && instanceID == "":
-		fatal("--instance-id is required for --resource recovery (or set EKS_INSTANCE_ID)")
+	if err := gatewayfetch.Run(context.Background(), cfg); err != nil {
+		slog.Error("eks-gateway-fetch: " + err.Error())
+		os.Exit(1)
 	}
-
-	client, err := eksgw.New(gatewayURL, gatewayCA, accessKey, secretKey, region)
-	if err != nil {
-		fatal(fmt.Sprintf("build gateway client: %v", err))
-	}
-
-	var (
-		path string
-		emit func(io.Writer, []byte) error
-	)
-	switch resource {
-	case "recovery":
-		path = "/clusters/" + clusterName + "/internal-recovery/" + accountID + "/" + instanceID
-		emit = emitRecoveryTSV
-	default:
-		path = "/clusters/" + clusterName + "/internal-addons/" + accountID
-		emit = emitAddonsTSV
-	}
-
-	var lastErr error
-	for attempt := 1; attempt <= maxAttempts; attempt++ {
-		body, err := client.Get(path)
-		if err != nil {
-			lastErr = err
-			slog.Warn("eks-gateway-fetch: attempt failed", "resource", resource, "attempt", attempt, "err", err)
-			if attempt < maxAttempts {
-				time.Sleep(retryDelay)
-			}
-			continue
-		}
-		if werr := emit(os.Stdout, body); werr != nil {
-			fatal(fmt.Sprintf("render response: %v", werr))
-		}
-		return
-	}
-	fatal(fmt.Sprintf("fetch failed after %d attempts: %v", maxAttempts, lastErr))
-}
-
-// emitAddonsTSV decodes the internal-addons response and writes one TSV line per
-// staged add-on to w. An empty add-on set writes nothing (the agent then GCs
-// every locally-rendered manifest), which is the correct steady state for a
-// cluster with no managed add-ons.
-func emitAddonsTSV(out io.Writer, body []byte) error {
-	var resp internalAddonsResponse
-	if err := json.Unmarshal(body, &resp); err != nil {
-		return fmt.Errorf("unmarshal internal-addons response: %w", err)
-	}
-	w := bufio.NewWriter(out)
-	for _, a := range resp.Addons {
-		cfg := base64.StdEncoding.EncodeToString([]byte(a.ConfigurationValues))
-		if _, err := fmt.Fprintf(w, "%s\t%s\t%s\t%s\n", a.AddonName, a.AddonVersion, a.ServiceAccountRoleArn, cfg); err != nil {
-			return err
-		}
-	}
-	return w.Flush()
-}
-
-// recoveryDirective mirrors the gateway's RecoveryDirective wire shape; duplicated
-// here to keep this tiny VM binary free of the handler package's dependency graph.
-type recoveryDirective struct {
-	Epoch            int64  `json:"epoch"`
-	Action           string `json:"action"`
-	Snapshot         string `json:"snapshot"`
-	SnapshotRequired bool   `json:"snapshotRequired"`
-}
-
-type internalRecoveryResponse struct {
-	Directive recoveryDirective `json:"directive"`
-}
-
-// emitRecoveryTSV decodes the recovery directive and writes a single
-// epoch\taction\tsnapshot\tsnapshotRequired line the on-VM k3s-recovery agent
-// consumes without a JSON parser. An unset action defaults to "none" (steady
-// state); snapshotRequired is 1 when the snapshot MUST restore (fresh DR seed
-// aborts boot on fetch failure) else 0.
-func emitRecoveryTSV(out io.Writer, body []byte) error {
-	var resp internalRecoveryResponse
-	if err := json.Unmarshal(body, &resp); err != nil {
-		return fmt.Errorf("unmarshal internal-recovery response: %w", err)
-	}
-	d := resp.Directive
-	if d.Action == "" {
-		d.Action = "none"
-	}
-	required := "0"
-	if d.SnapshotRequired {
-		required = "1"
-	}
-	if _, err := fmt.Fprintf(out, "%d\t%s\t%s\t%s\n", d.Epoch, d.Action, d.Snapshot, required); err != nil {
-		return err
-	}
-	return nil
-}
-
-func fatal(msg string) {
-	slog.Error("eks-gateway-fetch: " + msg)
-	os.Exit(1)
 }

cmd/eks-gateway-fetch/main_test.go

@@ -1,44 +0,0 @@
-package main
-
-import (
-	"bytes"
-	"encoding/base64"
-	"testing"
-)
-
-func TestEmitAddonsTSV(t *testing.T) {
-	body := []byte(`{"addons":[
-		{"addonName":"spinifex-noop","addonVersion":"0.1.0"},
-		{"addonName":"aws-load-balancer-controller","addonVersion":"2.8.1",
-		 "serviceAccountRoleArn":"arn:aws:iam::111122223333:role/alb",
-		 "configurationValues":"{\"replicaCount\":2}"}
-	]}`)
-
-	var buf bytes.Buffer
-	if err := emitAddonsTSV(&buf, body); err != nil {
-		t.Fatalf("emitAddonsTSV: %v", err)
-	}
-	cfg := base64.StdEncoding.EncodeToString([]byte(`{"replicaCount":2}`))
-	want := "spinifex-noop\t0.1.0\t\t\n" +
-		"aws-load-balancer-controller\t2.8.1\tarn:aws:iam::111122223333:role/alb\t" + cfg + "\n"
-	if buf.String() != want {
-		t.Fatalf("TSV mismatch:\n got: %q\nwant: %q", buf.String(), want)
-	}
-}
-
-func TestEmitAddonsTSV_Empty(t *testing.T) {
-	var buf bytes.Buffer
-	if err := emitAddonsTSV(&buf, []byte(`{"addons":[]}`)); err != nil {
-		t.Fatalf("emitAddonsTSV: %v", err)
-	}
-	if buf.Len() != 0 {
-		t.Fatalf("empty addon set must emit nothing, got %q", buf.String())
-	}
-}
-
-func TestEmitAddonsTSV_BadJSON(t *testing.T) {
-	var buf bytes.Buffer
-	if err := emitAddonsTSV(&buf, []byte(`{not-json`)); err == nil {
-		t.Fatal("expected error on malformed JSON")
-	}
-}

cmd/eks-gateway-publish/main.go

@@ -1,13 +1,6 @@
 // eks-gateway-publish runs inside the EKS K3s control-plane VM and relays a
-// single publication to the host through the AWS gateway, instead of dialing
-// core NATS directly.
-//
-// It reads a JSON payload on stdin, wraps it as
-// {accountId, channel, kind, payload}, SigV4-signs (service "eks") an HTTPS
-// POST to {gateway}/clusters/{cluster}/internal-publish, and retries with
-// backoff until the gateway returns 2xx or the attempt budget is exhausted —
-// so a degraded link surfaces as a non-zero exit rather than a silently
-// dropped message (the failure mode of fire-and-forget `nats pub`).
+// single JSON publication from stdin to the host through the AWS gateway; the
+// implementation is in agents/eks/gatewaypublish.
 //
 // Usage:
 //
@@ -20,115 +13,31 @@
 package main
 
 import (
-	"bytes"
-	"encoding/json"
+	"context"
 	"flag"
-	"fmt"
-	"io"
 	"log/slog"
 	"os"
-	"time"
 
-	"github.com/mulgadc/spinifex/internal/eksgw"
+	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
 
-	_ "github.com/mulgadc/spinifex/internal/fipsboot"
+	"github.com/mulgadc/spinifex/spinifex/agents/eks/gatewaypublish"
 )
 
-const (
-	// Retry budget: the control plane reaches readiness before this runs, so a
-	// failing POST means a degraded link, not a cold start. Bounded so a stuck
-	// boot still terminates the OpenRC service.
-	maxAttempts = 30
-	retryDelay  = 5 * time.Second
-)
-
-type publishBody struct {
-	AccountID string          `json:"accountId"`
-	Channel   string          `json:"channel"`
-	Kind      string          `json:"kind"`
-	Payload   json.RawMessage `json:"payload"`
-}
-
 func main() {
-	var (
-		gatewayURL  string
-		gatewayCA   string
-		accessKey   string
-		secretKey   string
-		region      string
-		accountID   string
-		clusterName string
-		channel     string
-		kind        string
-	)
-
-	flag.StringVar(&gatewayURL, "gateway", os.Getenv("EKS_GATEWAY_URL"), "Gateway URL (e.g. https://10.15.8.1:9999)")
-	flag.StringVar(&gatewayCA, "gateway-ca", os.Getenv("EKS_GATEWAY_CA"), "Path to gateway TLS CA PEM (optional; falls back to system trust)")
-	flag.StringVar(&accessKey, "access-key", os.Getenv("EKS_ACCESS_KEY"), "AWS access key ID")
-	flag.StringVar(&secretKey, "secret-key", os.Getenv("EKS_SECRET_KEY"), "AWS secret access key")
-	flag.StringVar(&region, "region", os.Getenv("EKS_REGION"), "AWS region for SigV4 signing")
-	flag.StringVar(&accountID, "account-id", os.Getenv("EKS_ACCOUNT_ID"), "Cluster account ID")
-	flag.StringVar(&clusterName, "cluster", os.Getenv("EKS_CLUSTER_NAME"), "Cluster name")
-	flag.StringVar(&channel, "channel", "", "Publish channel: bootstrap|state|addon")
-	flag.StringVar(&kind, "kind", "", "Bootstrap subject kind (bootstrap channel only)")
+	cfg := gatewaypublish.Config{Payload: os.Stdin}
+	flag.StringVar(&cfg.GatewayURL, "gateway", os.Getenv("EKS_GATEWAY_URL"), "Gateway URL (e.g. https://10.15.8.1:9999)")
+	flag.StringVar(&cfg.GatewayCA, "gateway-ca", os.Getenv("EKS_GATEWAY_CA"), "Path to gateway TLS CA PEM (optional; falls back to system trust)")
+	flag.StringVar(&cfg.AccessKey, "access-key", os.Getenv("EKS_ACCESS_KEY"), "AWS access key ID")
+	flag.StringVar(&cfg.SecretKey, "secret-key", os.Getenv("EKS_SECRET_KEY"), "AWS secret access key")
+	flag.StringVar(&cfg.Region, "region", os.Getenv("EKS_REGION"), "AWS region for SigV4 signing")
+	flag.StringVar(&cfg.AccountID, "account-id", os.Getenv("EKS_ACCOUNT_ID"), "Cluster account ID")
+	flag.StringVar(&cfg.ClusterName, "cluster", os.Getenv("EKS_CLUSTER_NAME"), "Cluster name")
+	flag.StringVar(&cfg.Channel, "channel", "", "Publish channel: bootstrap|state|addon")
+	flag.StringVar(&cfg.Kind, "kind", "", "Bootstrap subject kind (bootstrap channel only)")
 	flag.Parse()
 
-	switch {
-	case accountID == "":
-		fatal("--account-id is required (or set EKS_ACCOUNT_ID)")
-	case clusterName == "":
-		fatal("--cluster is required (or set EKS_CLUSTER_NAME)")
-	case channel != "bootstrap" && channel != "state" && channel != "addon":
-		fatal("--channel must be bootstrap, state or addon")
-	case channel == "bootstrap" && kind == "":
-		fatal("--kind is required for the bootstrap channel")
+	if err := gatewaypublish.Run(context.Background(), cfg); err != nil {
+		slog.Error("eks-gateway-publish: " + err.Error())
+		os.Exit(1)
 	}
-
-	payload, err := io.ReadAll(os.Stdin)
-	if err != nil {
-		fatal(fmt.Sprintf("read stdin payload: %v", err))
-	}
-	if len(bytes.TrimSpace(payload)) == 0 {
-		fatal("empty stdin payload")
-	}
-	if !json.Valid(payload) {
-		fatal("stdin payload is not valid JSON")
-	}
-
-	body, err := json.Marshal(publishBody{
-		AccountID: accountID,
-		Channel:   channel,
-		Kind:      kind,
-		Payload:   json.RawMessage(payload),
-	})
-	if err != nil {
-		fatal(fmt.Sprintf("marshal request body: %v", err))
-	}
-
-	client, err := eksgw.New(gatewayURL, gatewayCA, accessKey, secretKey, region)
-	if err != nil {
-		fatal(fmt.Sprintf("build gateway client: %v", err))
-	}
-	path := "/clusters/" + clusterName + "/internal-publish"
-
-	var lastErr error
-	for attempt := 1; attempt <= maxAttempts; attempt++ {
-		if _, err := client.Post(path, body); err != nil {
-			lastErr = err
-			slog.Warn("eks-gateway-publish: attempt failed",
-				"channel", channel, "kind", kind, "attempt", attempt, "err", err)
-			if attempt < maxAttempts {
-				time.Sleep(retryDelay)
-			}
-			continue
-		}
-		slog.Info("eks-gateway-publish: published", "channel", channel, "kind", kind)
-		return
-	}
-	fatal(fmt.Sprintf("publish failed after %d attempts: %v", maxAttempts, lastErr))
-}
-
-func fatal(msg string) {
-	slog.Error("eks-gateway-publish: " + msg)
-	os.Exit(1)
 }

cmd/eks-konnectivity-cert/main.go

@@ -1,16 +1,6 @@
-// Command eks-konnectivity-cert mints, then reuses, an ECDSA-P256 serving
-// certificate for the on-node konnectivity-server, signed by the K3s cluster CA.
-//
-// The konnectivity-agent (DaemonSet on workers) verifies the server it dials
-// using the in-pod ServiceAccount CA (/var/run/secrets/.../ca.crt), which in
-// K3s is the same server-ca that signs the apiserver. Signing the konnectivity
-// serving cert with that CA is therefore what lets the agent validate the
-// reverse-tunnel endpoint with no separate CA distribution.
-//
-// The eks-node AMI carries no openssl, so this is the Go equivalent: load the
-// K3s server CA cert+key, issue a leaf (ServerAuth) cert carrying the cluster's
-// konnectivity SANs (the NLB private-endpoint IP, public endpoint IP, NLB DNS),
-// and cache it under -dir so the OpenRC service is byte-stable across restarts.
+// Command eks-konnectivity-cert mints, then reuses, a K3s-CA-signed serving
+// certificate for the on-node konnectivity-server; the implementation is in
+// agents/eks/konnectivitycert.
 //
 // Usage:
 //
@@ -23,223 +13,27 @@
 package main
 
 import (
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	"crypto/rand"
-	"crypto/x509"
-	"crypto/x509/pkix"
-	"encoding/pem"
+	"context"
 	"flag"
-	"fmt"
 	"log/slog"
-	"math/big"
-	"net"
 	"os"
-	"path/filepath"
-	"strings"
-	"time"
+
+	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
+
+	"github.com/mulgadc/spinifex/spinifex/agents/eks/konnectivitycert"
 )
 
 func main() {
-	dir := flag.String("dir", "", "directory to cache tls.crt/tls.key in")
-	caCert := flag.String("ca-cert", "", "PEM path of the signing (K3s server) CA cert")
-	caKey := flag.String("ca-key", "", "PEM path of the signing CA private key")
-	cn := flag.String("cn", "konnectivity-server", "certificate common name")
-	sansCSV := flag.String("sans", "", "comma-separated SANs (IP or DNS)")
+	cfg := konnectivitycert.Config{Out: os.Stdout}
+	flag.StringVar(&cfg.Dir, "dir", "", "directory to cache tls.crt/tls.key in")
+	flag.StringVar(&cfg.CACert, "ca-cert", "", "PEM path of the signing (K3s server) CA cert")
+	flag.StringVar(&cfg.CAKey, "ca-key", "", "PEM path of the signing CA private key")
+	flag.StringVar(&cfg.CN, "cn", "konnectivity-server", "certificate common name")
+	flag.StringVar(&cfg.SANs, "sans", "", "comma-separated SANs (IP or DNS)")
 	flag.Parse()
 
-	if *dir == "" || *caCert == "" || *caKey == "" || *sansCSV == "" {
-		fatal("eks-konnectivity-cert: -dir, -ca-cert, -ca-key and -sans are required")
+	if err := konnectivitycert.Run(context.Background(), cfg); err != nil {
+		slog.Error("eks-konnectivity-cert: " + err.Error())
+		os.Exit(1)
 	}
-	dns, ips := splitSANs(*sansCSV)
-	if len(dns) == 0 && len(ips) == 0 {
-		fatal("eks-konnectivity-cert: -sans lists no usable names")
-	}
-
-	certPath, keyPath, err := ensureCert(*dir, *caCert, *caKey, *cn, dns, ips)
-	if err != nil {
-		fatal("eks-konnectivity-cert: " + err.Error())
-	}
-	fmt.Printf("%s\t%s\n", certPath, keyPath)
-}
-
-// ensureCert returns the cached cert/key paths under dir, minting and persisting
-// a fresh CA-signed pair when none is present, readable, and still SAN-current.
-func ensureCert(dir, caCertPath, caKeyPath, cn string, dns []string, ips []net.IP) (string, string, error) {
-	certPath := filepath.Join(dir, "tls.crt")
-	keyPath := filepath.Join(dir, "tls.key")
-
-	if certCoversSANs(certPath, keyPath, dns, ips) {
-		return certPath, keyPath, nil
-	}
-
-	caCert, caKey, err := loadCA(caCertPath, caKeyPath)
-	if err != nil {
-		return "", "", err
-	}
-	certPEM, keyPEM, err := issueLeaf(caCert, caKey, cn, dns, ips)
-	if err != nil {
-		return "", "", err
-	}
-	if err = os.MkdirAll(dir, 0o700); err != nil {
-		return "", "", fmt.Errorf("mkdir %s: %w", dir, err)
-	}
-	if err = os.WriteFile(certPath, certPEM, 0o644); err != nil {
-		return "", "", fmt.Errorf("write %s: %w", certPath, err)
-	}
-	if err = os.WriteFile(keyPath, keyPEM, 0o600); err != nil {
-		return "", "", fmt.Errorf("write %s: %w", keyPath, err)
-	}
-	return certPath, keyPath, nil
-}
-
-// certCoversSANs reports whether the cached cert exists, parses, has a key, and
-// already carries every requested SAN — so a cert minted before the endpoint
-// set changed is re-issued rather than served stale.
-func certCoversSANs(certPath, keyPath string, dns []string, ips []net.IP) bool {
-	c, err := os.ReadFile(certPath)
-	if err != nil {
-		return false
-	}
-	if k, kerr := os.ReadFile(keyPath); kerr != nil || len(k) == 0 {
-		return false
-	}
-	der := decodeFirst(c)
-	if der == nil {
-		return false
-	}
-	crt, err := x509.ParseCertificate(der)
-	if err != nil {
-		return false
-	}
-	have := make(map[string]struct{}, len(crt.DNSNames)+len(crt.IPAddresses))
-	for _, n := range crt.DNSNames {
-		have[n] = struct{}{}
-	}
-	for _, ip := range crt.IPAddresses {
-		have[ip.String()] = struct{}{}
-	}
-	for _, n := range dns {
-		if _, ok := have[n]; !ok {
-			return false
-		}
-	}
-	for _, ip := range ips {
-		if _, ok := have[ip.String()]; !ok {
-			return false
-		}
-	}
-	return true
-}
-
-// loadCA parses the PEM CA cert + EC/PKCS8 private key used to sign the leaf.
-func loadCA(certPath, keyPath string) (*x509.Certificate, *ecdsa.PrivateKey, error) {
-	certPEM, err := os.ReadFile(certPath)
-	if err != nil {
-		return nil, nil, fmt.Errorf("read ca cert %s: %w", certPath, err)
-	}
-	der := decodeFirst(certPEM)
-	if der == nil {
-		return nil, nil, fmt.Errorf("ca cert %s: no PEM block", certPath)
-	}
-	caCert, err := x509.ParseCertificate(der)
-	if err != nil {
-		return nil, nil, fmt.Errorf("parse ca cert: %w", err)
-	}
-
-	keyPEM, err := os.ReadFile(keyPath)
-	if err != nil {
-		return nil, nil, fmt.Errorf("read ca key %s: %w", keyPath, err)
-	}
-	keyDER := decodeFirst(keyPEM)
-	if keyDER == nil {
-		return nil, nil, fmt.Errorf("ca key %s: no PEM block", keyPath)
-	}
-	caKey, err := parseECKey(keyDER)
-	if err != nil {
-		return nil, nil, err
-	}
-	return caCert, caKey, nil
-}
-
-// parseECKey accepts the EC SEC1 or PKCS8 encodings K3s may write for the CA key.
-func parseECKey(der []byte) (*ecdsa.PrivateKey, error) {
-	if k, err := x509.ParseECPrivateKey(der); err == nil {
-		return k, nil
-	}
-	k8, err := x509.ParsePKCS8PrivateKey(der)
-	if err != nil {
-		return nil, fmt.Errorf("parse ca key (sec1 and pkcs8 failed): %w", err)
-	}
-	ec, ok := k8.(*ecdsa.PrivateKey)
-	if !ok {
-		return nil, fmt.Errorf("ca key is %T, want ecdsa", k8)
-	}
-	return ec, nil
-}
-
-// issueLeaf mints an ECDSA-P256 ServerAuth leaf for cn + SANs, signed by caCert/caKey.
-func issueLeaf(caCert *x509.Certificate, caKey *ecdsa.PrivateKey, cn string, dns []string, ips []net.IP) (certPEM, keyPEM []byte, err error) {
-	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		return nil, nil, fmt.Errorf("generate key: %w", err)
-	}
-	serial, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
-	if err != nil {
-		return nil, nil, fmt.Errorf("serial: %w", err)
-	}
-	now := time.Now().UTC()
-	tmpl := x509.Certificate{
-		SerialNumber:          serial,
-		Subject:               pkix.Name{CommonName: cn},
-		NotBefore:             now.Add(-time.Hour),
-		NotAfter:              now.AddDate(10, 0, 0),
-		KeyUsage:              x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment,
-		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
-		BasicConstraintsValid: true,
-		DNSNames:              dns,
-		IPAddresses:           ips,
-	}
-	der, err := x509.CreateCertificate(rand.Reader, &tmpl, caCert, &priv.PublicKey, caKey)
-	if err != nil {
-		return nil, nil, fmt.Errorf("create cert: %w", err)
-	}
-	keyDER, err := x509.MarshalECPrivateKey(priv)
-	if err != nil {
-		return nil, nil, fmt.Errorf("marshal key: %w", err)
-	}
-	certPEM = pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der})
-	keyPEM = pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: keyDER})
-	return certPEM, keyPEM, nil
-}
-
-// splitSANs partitions the CSV into DNS names and IPs (an entry that parses as an
-// IP goes to IPAddresses, else DNSNames), matching how SAN matching is typed.
-func splitSANs(s string) (dns []string, ips []net.IP) {
-	for p := range strings.SplitSeq(s, ",") {
-		p = strings.TrimSpace(p)
-		if p == "" {
-			continue
-		}
-		if ip := net.ParseIP(p); ip != nil {
-			ips = append(ips, ip)
-			continue
-		}
-		dns = append(dns, p)
-	}
-	return dns, ips
-}
-
-// decodeFirst returns the DER bytes of the first PEM block, or nil.
-func decodeFirst(pemBytes []byte) []byte {
-	blk, _ := pem.Decode(pemBytes)
-	if blk == nil {
-		return nil
-	}
-	return blk.Bytes
-}
-
-func fatal(msg string) {
-	slog.Error(msg)
-	os.Exit(1)
 }

cmd/eks-konnectivity-cert/main_test.go

@@ -1,153 +0,0 @@
-package main
-
-import (
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	"crypto/rand"
-	"crypto/x509"
-	"crypto/x509/pkix"
-	"encoding/pem"
-	"math/big"
-	"net"
-	"os"
-	"path/filepath"
-	"testing"
-	"time"
-)
-
-// writeTestCA mints a self-signed EC CA (cert + SEC1 key PEM) into dir, returning
-// the two paths — a stand-in for K3s' /var/lib/rancher/k3s/server/tls/server-ca.*.
-func writeTestCA(t *testing.T, dir string) (certPath, keyPath string) {
-	t.Helper()
-	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatalf("gen ca key: %v", err)
-	}
-	tmpl := x509.Certificate{
-		SerialNumber:          big.NewInt(1),
-		Subject:               pkix.Name{CommonName: "k3s-server-ca"},
-		NotBefore:             time.Now().Add(-time.Hour),
-		NotAfter:              time.Now().AddDate(10, 0, 0),
-		KeyUsage:              x509.KeyUsageCertSign | x509.KeyUsageDigitalSignature,
-		BasicConstraintsValid: true,
-		IsCA:                  true,
-	}
-	der, err := x509.CreateCertificate(rand.Reader, &tmpl, &tmpl, &priv.PublicKey, priv)
-	if err != nil {
-		t.Fatalf("create ca cert: %v", err)
-	}
-	keyDER, err := x509.MarshalECPrivateKey(priv)
-	if err != nil {
-		t.Fatalf("marshal ca key: %v", err)
-	}
-	certPath = filepath.Join(dir, "server-ca.crt")
-	keyPath = filepath.Join(dir, "server-ca.key")
-	if err := os.WriteFile(certPath, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der}), 0o644); err != nil {
-		t.Fatalf("write ca cert: %v", err)
-	}
-	if err := os.WriteFile(keyPath, pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: keyDER}), 0o600); err != nil {
-		t.Fatalf("write ca key: %v", err)
-	}
-	return certPath, keyPath
-}
-
-func leafFrom(t *testing.T, certPath string) *x509.Certificate {
-	t.Helper()
-	b, err := os.ReadFile(certPath)
-	if err != nil {
-		t.Fatalf("read leaf: %v", err)
-	}
-	crt, err := x509.ParseCertificate(decodeFirst(b))
-	if err != nil {
-		t.Fatalf("parse leaf: %v", err)
-	}
-	return crt
-}
-
-func TestEnsureCertSignsLeafWithSANsThatChainsToCA(t *testing.T) {
-	dir := t.TempDir()
-	caCert, caKey := writeTestCA(t, dir)
-
-	dns, ips := splitSANs("10.32.100.4,203.0.113.9,eks-toc.example")
-	certPath, keyPath, err := ensureCert(dir, caCert, caKey, "konnectivity-server", dns, ips)
-	if err != nil {
-		t.Fatalf("ensureCert: %v", err)
-	}
-	if _, err := os.Stat(keyPath); err != nil {
-		t.Fatalf("key not written: %v", err)
-	}
-
-	leaf := leafFrom(t, certPath)
-	if leaf.IsCA {
-		t.Error("konnectivity serving cert must be a leaf, not a CA")
-	}
-	// The agent dials the NLB private-endpoint IP and verifies via the in-pod CA,
-	// so the IP must be a SAN or the tunnel TLS handshake fails.
-	if err := leaf.VerifyHostname("10.32.100.4"); err != nil {
-		t.Errorf("IP SAN 10.32.100.4 missing: %v", err)
-	}
-
-	// The leaf must chain to the K3s server CA — that CA is the in-pod ca.crt the
-	// agent trusts, so no separate CA distribution is needed.
-	caPEM, _ := os.ReadFile(caCert)
-	roots := x509.NewCertPool()
-	if !roots.AppendCertsFromPEM(caPEM) {
-		t.Fatal("append CA failed")
-	}
-	if _, err := leaf.Verify(x509.VerifyOptions{
-		Roots:     roots,
-		DNSName:   "eks-toc.example",
-		KeyUsages: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
-	}); err != nil {
-		t.Errorf("leaf does not chain to the K3s server CA: %v", err)
-	}
-}
-
-func TestEnsureCertReusesThenReissuesOnSANChange(t *testing.T) {
-	dir := t.TempDir()
-	caCert, caKey := writeTestCA(t, dir)
-
-	dns, ips := splitSANs("10.32.100.4,eks-toc.example")
-	c1, _, err := ensureCert(dir, caCert, caKey, "konnectivity-server", dns, ips)
-	if err != nil {
-		t.Fatalf("first ensureCert: %v", err)
-	}
-	first, _ := os.ReadFile(c1)
-
-	// Same SANs → cached pair reused byte-for-byte (a churning cert would bounce
-	// the konnectivity-server on every restart).
-	if _, _, err := ensureCert(dir, caCert, caKey, "konnectivity-server", dns, ips); err != nil {
-		t.Fatalf("second ensureCert: %v", err)
-	}
-	if second, _ := os.ReadFile(c1); string(first) != string(second) {
-		t.Error("ensureCert re-minted instead of reusing the SAN-current cached cert")
-	}
-
-	// A new endpoint in the SAN set must force a re-issue.
-	dns2, ips2 := splitSANs("10.32.100.4,eks-toc.example,10.32.100.99")
-	if _, _, err := ensureCert(dir, caCert, caKey, "konnectivity-server", dns2, ips2); err != nil {
-		t.Fatalf("third ensureCert: %v", err)
-	}
-	if third, _ := os.ReadFile(c1); string(first) == string(third) {
-		t.Error("ensureCert served a stale cert that does not cover the new SAN")
-	}
-	if err := leafFrom(t, c1).VerifyHostname("10.32.100.99"); err != nil {
-		t.Errorf("re-issued cert missing new SAN: %v", err)
-	}
-}
-
-func TestSplitSANsPartitionsIPsAndDNS(t *testing.T) {
-	dns, ips := splitSANs(" 10.0.0.1 , host.example , , 2001:db8::1 ")
-	if len(dns) != 1 || dns[0] != "host.example" {
-		t.Errorf("dns = %v, want [host.example]", dns)
-	}
-	wantIPs := []net.IP{net.ParseIP("10.0.0.1"), net.ParseIP("2001:db8::1")}
-	if len(ips) != len(wantIPs) {
-		t.Fatalf("ips = %v, want %v", ips, wantIPs)
-	}
-	for i, ip := range ips {
-		if !ip.Equal(wantIPs[i]) {
-			t.Errorf("ips[%d] = %v, want %v", i, ip, wantIPs[i])
-		}
-	}
-}

cmd/eks-token-webhook/cert.go

@@ -1,133 +0,0 @@
-package main
-
-import (
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	"crypto/rand"
-	"crypto/tls"
-	"crypto/x509"
-	"crypto/x509/pkix"
-	"encoding/base64"
-	"encoding/pem"
-	"fmt"
-	"math/big"
-	"net"
-	"os"
-	"time"
-
-	"github.com/mulgadc/spinifex/internal/tlsconfig"
-)
-
-// serverTLSConfig is the webhook's loopback serving TLS config.
-func serverTLSConfig(cert tls.Certificate) *tls.Config {
-	return &tls.Config{
-		Certificates:     []tls.Certificate{cert},
-		MinVersion:       tls.VersionTLS13,
-		CurvePreferences: tlsconfig.Curves,
-	}
-}
-
-// ensureServingCert loads the persisted self-signed serving cert/key, or mints
-// a fresh ECDSA-P256 pair (SAN 127.0.0.1 / localhost) and persists it. Reusing
-// across restarts keeps the CA the apiserver loaded into its webhook kubeconfig
-// valid even if the webhook process is restarted. Returns the parsed cert and
-// the certificate PEM (for embedding as the kubeconfig CA bundle).
-func ensureServingCert(certPath, keyPath string) (tls.Certificate, []byte, error) {
-	if certPEM, keyPEM, ok := readCertPair(certPath, keyPath); ok {
-		cert, err := tls.X509KeyPair(certPEM, keyPEM)
-		if err == nil {
-			return cert, certPEM, nil
-		}
-		// Fall through to regenerate on a corrupt/incompatible persisted pair.
-	}
-
-	certPEM, keyPEM, err := generateSelfSigned()
-	if err != nil {
-		return tls.Certificate{}, nil, err
-	}
-	if err := os.WriteFile(certPath, certPEM, 0o644); err != nil {
-		return tls.Certificate{}, nil, fmt.Errorf("write cert %s: %w", certPath, err)
-	}
-	if err := os.WriteFile(keyPath, keyPEM, 0o600); err != nil {
-		return tls.Certificate{}, nil, fmt.Errorf("write key %s: %w", keyPath, err)
-	}
-	cert, err := tls.X509KeyPair(certPEM, keyPEM)
-	if err != nil {
-		return tls.Certificate{}, nil, fmt.Errorf("parse minted keypair: %w", err)
-	}
-	return cert, certPEM, nil
-}
-
-func readCertPair(certPath, keyPath string) (certPEM, keyPEM []byte, ok bool) {
-	c, err := os.ReadFile(certPath)
-	if err != nil {
-		return nil, nil, false
-	}
-	k, err := os.ReadFile(keyPath)
-	if err != nil {
-		return nil, nil, false
-	}
-	return c, k, true
-}
-
-func generateSelfSigned() (certPEM, keyPEM []byte, err error) {
-	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		return nil, nil, fmt.Errorf("generate key: %w", err)
-	}
-	serial, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
-	if err != nil {
-		return nil, nil, fmt.Errorf("serial: %w", err)
-	}
-	now := time.Now().UTC()
-	tmpl := x509.Certificate{
-		SerialNumber:          serial,
-		Subject:               pkix.Name{CommonName: "eks-token-webhook"},
-		NotBefore:             now.Add(-time.Hour),
-		NotAfter:              now.AddDate(10, 0, 0),
-		KeyUsage:              x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment | x509.KeyUsageCertSign,
-		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
-		BasicConstraintsValid: true,
-		IsCA:                  true,
-		IPAddresses:           []net.IP{net.IPv4(127, 0, 0, 1), net.IPv6loopback},
-		DNSNames:              []string{"localhost"},
-	}
-	der, err := x509.CreateCertificate(rand.Reader, &tmpl, &tmpl, &priv.PublicKey, priv)
-	if err != nil {
-		return nil, nil, fmt.Errorf("create cert: %w", err)
-	}
-	keyDER, err := x509.MarshalECPrivateKey(priv)
-	if err != nil {
-		return nil, nil, fmt.Errorf("marshal key: %w", err)
-	}
-	certPEM = pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der})
-	keyPEM = pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: keyDER})
-	return certPEM, keyPEM, nil
-}
-
-// writeAPIServerKubeconfig writes the kubeconfig kube-apiserver loads via
-// --authentication-token-webhook-config-file. It points the apiserver at the
-// loopback webhook and trusts its self-signed serving cert as the CA bundle.
-func writeAPIServerKubeconfig(path, addr string, certPEM []byte) error {
-	caB64 := base64.StdEncoding.EncodeToString(certPEM)
-	kubeconfig := fmt.Sprintf(`apiVersion: v1
-kind: Config
-clusters:
-- name: mulga-eks-token-webhook
-  cluster:
-    certificate-authority-data: %s
-    server: https://%s/authenticate
-users:
-- name: kube-apiserver
-contexts:
-- name: webhook
-  context:
-    cluster: mulga-eks-token-webhook
-    user: kube-apiserver
-current-context: webhook
-`, caB64, addr)
-	if err := os.WriteFile(path, []byte(kubeconfig), 0o600); err != nil {
-		return fmt.Errorf("write %s: %w", path, err)
-	}
-	return nil
-}

cmd/eks-token-webhook/main.go

@@ -1,74 +1,45 @@
-// eks-token-webhook is the K8s TokenReview webhook authenticator baked into
-// the eks-server AMI. Per kubectl call the kube-apiserver POSTs the bearer
-// token (produced by `aws eks get-token`); the webhook relays it through the
-// AWS gateway broker (SigV4 HTTPS POST to /clusters/{name}/token-review), which
-// host-side runs the STS verify (cross-cluster x-k8s-aws-id pin) + AccessEntry
-// KV lookup and returns the resolved identity. The webhook never speaks core
-// NATS — same gateway-broker model as ELBv2's lb-agent and eks-gateway-publish.
-//
-// It binds 127.0.0.1 only; the kube-apiserver is the sole client (loopback).
-// On startup it writes the apiserver webhook kubeconfig (with its self-signed
-// serving CA) so k3s can be pointed at it via
-// --authentication-token-webhook-config-file.
-//
-// SigV4 creds come from the AWS SDK chain (IMDS instance-role) when static
-// EKS_ACCESS_KEY/EKS_SECRET_KEY are absent, matching the sibling helpers.
+// Command eks-token-webhook is the K8s TokenReview webhook authenticator baked
+// into the eks-server AMI; the implementation is in agents/eks/tokenwebhook.
+// It reads its configuration from the first-boot env cloud-init seeds onto the
+// VM and binds loopback only.
 package main
 
 import (
-	"encoding/json"
+	"context"
 	"errors"
 	"flag"
-	"fmt"
 	"log/slog"
-	"net/http"
 	"os"
-	"time"
 
-	"github.com/mulgadc/spinifex/internal/eksgw"
-	handlers_eks "github.com/mulgadc/spinifex/spinifex/handlers/eks"
+	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
+
+	"github.com/mulgadc/spinifex/spinifex/agents/eks/tokenwebhook"
 )
 
-// config is the webhook's runtime configuration, sourced from the first-boot
-// env (/etc/spinifex-eks/first-boot.env) cloud-init seeds onto the VM.
-type config struct {
-	addr        string
-	gatewayURL  string
-	gatewayCA   string
-	accessKey   string
-	secretKey   string
-	region      string
-	accountID   string
-	clusterName string
-	certPath    string
-	keyPath     string
-	kubeconfig  string
-}
-
-func loadConfig() (config, error) {
-	c := config{
-		addr:        flagAddr,
-		gatewayURL:  os.Getenv("EKS_GATEWAY_URL"),
-		gatewayCA:   os.Getenv("EKS_GATEWAY_CA"),
-		accessKey:   os.Getenv("EKS_ACCESS_KEY"),
-		secretKey:   os.Getenv("EKS_SECRET_KEY"),
-		region:      os.Getenv("EKS_REGION"),
-		accountID:   os.Getenv("EKS_ACCOUNT_ID"),
-		clusterName: os.Getenv("EKS_CLUSTER_NAME"),
-		certPath:    envOr("EKS_WEBHOOK_CERT", "/etc/spinifex-eks/token-webhook.crt"),
-		keyPath:     envOr("EKS_WEBHOOK_KEY", "/etc/spinifex-eks/token-webhook.key"),
-		kubeconfig:  envOr("EKS_WEBHOOK_KUBECONFIG", "/etc/spinifex-eks/token-webhook.kubeconfig"),
+func loadConfig() (tokenwebhook.Config, error) {
+	c := tokenwebhook.Config{
+		Addr:        flagAddr,
+		GatewayURL:  os.Getenv("EKS_GATEWAY_URL"),
+		GatewayCA:   os.Getenv("EKS_GATEWAY_CA"),
+		AccessKey:   os.Getenv("EKS_ACCESS_KEY"),
+		SecretKey:   os.Getenv("EKS_SECRET_KEY"),
+		Region:      os.Getenv("EKS_REGION"),
+		AccountID:   os.Getenv("EKS_ACCOUNT_ID"),
+		ClusterName: os.Getenv("EKS_CLUSTER_NAME"),
+		CertPath:    envOr("EKS_WEBHOOK_CERT", "/etc/spinifex-eks/token-webhook.crt"),
+		KeyPath:     envOr("EKS_WEBHOOK_KEY", "/etc/spinifex-eks/token-webhook.key"),
+		Kubeconfig:  envOr("EKS_WEBHOOK_KUBECONFIG", "/etc/spinifex-eks/token-webhook.kubeconfig"),
 	}
 	// Static SigV4 creds are optional: when absent, eksgw.New signs with the
 	// AWS SDK chain (IMDS instance-role creds), the same path the CP VM's
 	// sibling helpers use. The CP VM launches on an instance profile, so
 	// buildK3sUserData omits EKS_ACCESS_KEY/EKS_SECRET_KEY by design.
 	switch {
-	case c.gatewayURL == "":
+	case c.GatewayURL == "":
 		return c, errors.New("EKS_GATEWAY_URL not set")
-	case c.accountID == "":
+	case c.AccountID == "":
 		return c, errors.New("EKS_ACCOUNT_ID not set")
-	case c.clusterName == "":
+	case c.ClusterName == "":
 		return c, errors.New("EKS_CLUSTER_NAME not set")
 	}
 	return c, nil
@@ -95,132 +66,8 @@ func main() {
 		os.Exit(1)
 	}
 
-	if err := run(cfg); err != nil {
+	if err := tokenwebhook.Run(context.Background(), cfg); err != nil {
 		slog.Error("eks-token-webhook fatal", "err", err)
 		os.Exit(1)
 	}
 }
-
-func run(cfg config) error {
-	// Serving cert + apiserver kubeconfig. Persisted and reused across restarts
-	// so a webhook crash does not invalidate the CA the apiserver already loaded.
-	tlsCert, certPEM, err := ensureServingCert(cfg.certPath, cfg.keyPath)
-	if err != nil {
-		return fmt.Errorf("serving cert: %w", err)
-	}
-	if err := writeAPIServerKubeconfig(cfg.kubeconfig, cfg.addr, certPEM); err != nil {
-		return fmt.Errorf("write apiserver kubeconfig: %w", err)
-	}
-
-	client, err := eksgw.New(cfg.gatewayURL, cfg.gatewayCA, cfg.accessKey, cfg.secretKey, cfg.region)
-	if err != nil {
-		return fmt.Errorf("build gateway client: %w", err)
-	}
-
-	authr := &authenticator{
-		accountID:   cfg.accountID,
-		clusterName: cfg.clusterName,
-		review:      gatewayReviewer(client, cfg.clusterName, cfg.accountID),
-	}
-
-	mux := http.NewServeMux()
-	mux.HandleFunc("/healthz", func(w http.ResponseWriter, _ *http.Request) {
-		w.WriteHeader(http.StatusOK)
-		_, _ = w.Write([]byte("ok"))
-	})
-	mux.HandleFunc("/authenticate", authr.handle)
-
-	server := &http.Server{
-		Addr:              cfg.addr,
-		Handler:           mux,
-		ReadHeaderTimeout: 5 * time.Second,
-		TLSConfig:         serverTLSConfig(tlsCert),
-	}
-	slog.Info("eks-token-webhook listening", "addr", cfg.addr, "cluster", cfg.clusterName)
-	if err := server.ListenAndServeTLS("", ""); err != nil && !errors.Is(err, http.ErrServerClosed) {
-		return fmt.Errorf("serve: %w", err)
-	}
-	return nil
-}
-
-// tokenReviewRequest is the body POSTed to /clusters/{name}/token-review. The
-// webhook holds system SigV4 creds (system account, not the cluster account),
-// so accountId names the cluster account explicitly — same as PublishInternal.
-type tokenReviewRequest struct {
-	AccountID string `json:"accountId"`
-	Token     string `json:"token"`
-}
-
-// gatewayReviewer returns the per-call relay: SigV4-POST {accountId,token} to
-// the gateway and decode the resolved identity. A non-2xx / transport error is
-// surfaced (handle() turns it into a 5xx so the apiserver retries) rather than a
-// silent deny, distinguishing "webhook broker down" from "token rejected".
-func gatewayReviewer(client *eksgw.Client, clusterName, accountID string) func(string) (handlers_eks.WebhookTokenReviewResult, error) {
-	path := "/clusters/" + clusterName + "/token-review"
-	return func(token string) (handlers_eks.WebhookTokenReviewResult, error) {
-		body, err := json.Marshal(tokenReviewRequest{AccountID: accountID, Token: token})
-		if err != nil {
-			return handlers_eks.WebhookTokenReviewResult{}, fmt.Errorf("marshal request: %w", err)
-		}
-		respBody, err := client.Post(path, body)
-		if err != nil {
-			return handlers_eks.WebhookTokenReviewResult{}, err
-		}
-		var res handlers_eks.WebhookTokenReviewResult
-		if err := json.Unmarshal(respBody, &res); err != nil {
-			return handlers_eks.WebhookTokenReviewResult{}, fmt.Errorf("decode response: %w", err)
-		}
-		return res, nil
-	}
-}
-
-// authenticator resolves a TokenReview by relaying to the gateway broker.
-type authenticator struct {
-	accountID   string
-	clusterName string
-	review      func(token string) (handlers_eks.WebhookTokenReviewResult, error)
-}
-
-func (a *authenticator) handle(w http.ResponseWriter, r *http.Request) {
-	if r.Method != http.MethodPost {
-		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
-		return
-	}
-	var review tokenReview
-	if err := json.NewDecoder(r.Body).Decode(&review); err != nil {
-		http.Error(w, "bad request", http.StatusBadRequest)
-		return
-	}
-
-	res, err := a.review(review.Spec.Token)
-	if err != nil {
-		// Broker fault (gateway down, transport error): a 5xx tells the apiserver
-		// to retry rather than treating a transient outage as a hard deny.
-		slog.Error("TokenReview relay failed", "cluster", a.clusterName, "err", err)
-		http.Error(w, "token review unavailable", http.StatusServiceUnavailable)
-		return
-	}
-
-	status := tokenReviewStatus{Authenticated: res.Authenticated}
-	if res.Authenticated {
-		status.User = userInfo{
-			Username: res.Username,
-			UID:      res.UID,
-			Groups:   res.Groups,
-		}
-		// Confirm the token for the audiences the apiserver asked about; an empty
-		// status.audiences is rejected when --api-audiences is configured.
-		status.Audiences = review.Spec.Audiences
-	}
-	slog.Info("TokenReview decision", "authenticated", status.Authenticated, "username", status.User.Username, "audiences", status.Audiences)
-
-	resp := tokenReview{
-		APIVersion: "authentication.k8s.io/v1",
-		Kind:       "TokenReview",
-		Status:     status,
-	}
-	w.Header().Set("Content-Type", "application/json")
-	if err := json.NewEncoder(w).Encode(resp); err != nil {
-		slog.Error("encode TokenReview response", "err", err)
-	}
-}

cmd/eks-token-webhook/main_test.go

@@ -1,127 +1,12 @@
 package main
 
 import (
-	"encoding/base64"
-	"encoding/json"
-	"errors"
-	"net/http"
-	"net/http/httptest"
-	"os"
-	"path/filepath"
-	"strings"
 	"testing"
 
-	handlers_eks "github.com/mulgadc/spinifex/spinifex/handlers/eks"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
-// postReview drives authenticator.handle with a TokenReview carrying token and
-// audiences, returning the decoded response status and HTTP code.
-func postReview(t *testing.T, a *authenticator, token string, audiences []string) (tokenReviewStatus, int) {
-	t.Helper()
-	body, err := json.Marshal(tokenReview{
-		APIVersion: "authentication.k8s.io/v1",
-		Kind:       "TokenReview",
-		Spec:       tokenReviewSpec{Token: token, Audiences: audiences},
-	})
-	require.NoError(t, err)
-
-	req := httptest.NewRequest(http.MethodPost, "/authenticate", strings.NewReader(string(body)))
-	w := httptest.NewRecorder()
-	a.handle(w, req)
-
-	if w.Code != http.StatusOK {
-		return tokenReviewStatus{}, w.Code
-	}
-	var resp tokenReview
-	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))
-	return resp.Status, w.Code
-}
-
-func TestHandle_GrantsAndStampsAudiences(t *testing.T) {
-	a := &authenticator{
-		accountID:   "111122223333",
-		clusterName: "alpha",
-		review: func(string) (handlers_eks.WebhookTokenReviewResult, error) {
-			return handlers_eks.WebhookTokenReviewResult{
-				Authenticated: true,
-				Username:      "arn:aws:iam::111122223333:role/admin",
-				UID:           "AROAEXAMPLE:session",
-				Groups:        []string{"system:masters"},
-			}, nil
-		},
-	}
-
-	status, code := postReview(t, a, "tok", []string{"https://kubernetes.default.svc"})
-	require.Equal(t, http.StatusOK, code)
-	require.True(t, status.Authenticated)
-	assert.Equal(t, "arn:aws:iam::111122223333:role/admin", status.User.Username)
-	assert.Equal(t, "AROAEXAMPLE:session", status.User.UID)
-	assert.Equal(t, []string{"system:masters"}, status.User.Groups)
-	assert.Equal(t, []string{"https://kubernetes.default.svc"}, status.Audiences)
-}
-
-func TestHandle_DeniesWithoutStampingAudiences(t *testing.T) {
-	a := &authenticator{
-		clusterName: "alpha",
-		review: func(string) (handlers_eks.WebhookTokenReviewResult, error) {
-			return handlers_eks.WebhookTokenReviewResult{Authenticated: false}, nil
-		},
-	}
-
-	status, code := postReview(t, a, "tok", []string{"https://kubernetes.default.svc"})
-	require.Equal(t, http.StatusOK, code)
-	assert.False(t, status.Authenticated)
-	assert.Empty(t, status.User.Username)
-	assert.Empty(t, status.Audiences, "unauthenticated review must not stamp audiences")
-}
-
-// A broker fault is a 5xx (retryable), not a silent deny — a transient gateway
-// outage must not look identical to a rejected token.
-func TestHandle_BrokerFaultReturns5xx(t *testing.T) {
-	a := &authenticator{
-		clusterName: "alpha",
-		review: func(string) (handlers_eks.WebhookTokenReviewResult, error) {
-			return handlers_eks.WebhookTokenReviewResult{}, errors.New("gateway returned 503")
-		},
-	}
-
-	_, code := postReview(t, a, "tok", nil)
-	assert.Equal(t, http.StatusServiceUnavailable, code)
-}
-
-func TestEnsureServingCert_PersistsAndReuses(t *testing.T) {
-	dir := t.TempDir()
-	certPath := filepath.Join(dir, "wh.crt")
-	keyPath := filepath.Join(dir, "wh.key")
-
-	c1, pem1, err := ensureServingCert(certPath, keyPath)
-	require.NoError(t, err)
-	require.NotEmpty(t, pem1)
-	require.NotNil(t, serverTLSConfig(c1))
-
-	// Second call reuses the persisted pair (same cert bytes).
-	_, pem2, err := ensureServingCert(certPath, keyPath)
-	require.NoError(t, err)
-	assert.Equal(t, pem1, pem2)
-}
-
-func TestWriteAPIServerKubeconfig(t *testing.T) {
-	dir := t.TempDir()
-	path := filepath.Join(dir, "wh.kubeconfig")
-	certPEM := []byte("-----BEGIN CERTIFICATE-----\nMIIB\n-----END CERTIFICATE-----\n")
-
-	require.NoError(t, writeAPIServerKubeconfig(path, "127.0.0.1:8443", certPEM))
-
-	data, err := os.ReadFile(path)
-	require.NoError(t, err)
-	body := string(data)
-	assert.Contains(t, body, "server: https://127.0.0.1:8443/authenticate")
-	assert.Contains(t, body, base64.StdEncoding.EncodeToString(certPEM))
-	assert.Contains(t, body, "current-context: webhook")
-}
-
 // The CP VM launches on an instance profile, so cloud-init omits the static
 // EKS_ACCESS_KEY/EKS_SECRET_KEY and eksgw.New signs with IMDS creds. loadConfig
 // must accept absent static keys; gating on them aborts every IMDS-mode boot,
@@ -148,8 +33,8 @@ func TestLoadConfig_AcceptsAbsentStaticCreds(t *testing.T) {
 	})
 	cfg, err := loadConfig()
 	require.NoError(t, err)
-	assert.Empty(t, cfg.accessKey)
-	assert.Empty(t, cfg.secretKey)
+	assert.Empty(t, cfg.AccessKey)
+	assert.Empty(t, cfg.SecretKey)
 
 	// Genuinely-required vars are still enforced.
 	setEnv(t, map[string]string{

cmd/eks-webhook-cert/main.go

@@ -1,12 +1,6 @@
-// Command eks-webhook-cert mints, then reuses, a self-signed ECDSA-P256 serving
-// certificate for an in-cluster admission webhook and prints its base64 PEM so
-// the addon renderer can embed it as the webhook Secret + each caBundle.
-//
-// The eks-node AMI carries no openssl, so this is the Go equivalent of the
-// upstream Helm chart's install-time genSelfSignedCert: one cert per cluster,
-// cached on disk under -dir, stable across addon-sync ticks. The single cert is
-// its own CA (IsCA + ServerAuth), so the same PEM serves as both the TLS leaf
-// and the caBundle the apiserver trusts.
+// Command eks-webhook-cert mints, then reuses, a self-signed serving certificate
+// for an in-cluster admission webhook and prints its base64 PEM; the
+// implementation is in agents/eks/webhookcert.
 //
 // Usage:
 //
@@ -17,131 +11,25 @@
 package main
 
 import (
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	"crypto/rand"
-	"crypto/x509"
-	"crypto/x509/pkix"
-	"encoding/base64"
-	"encoding/pem"
+	"context"
 	"flag"
-	"fmt"
 	"log/slog"
-	"math/big"
 	"os"
-	"path/filepath"
-	"strings"
-	"time"
+
+	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
+
+	"github.com/mulgadc/spinifex/spinifex/agents/eks/webhookcert"
 )
 
 func main() {
-	dir := flag.String("dir", "", "directory to cache tls.crt/tls.key in")
-	cn := flag.String("cn", "", "certificate common name")
-	dnsCSV := flag.String("dns", "", "comma-separated DNS SANs")
+	cfg := webhookcert.Config{Out: os.Stdout}
+	flag.StringVar(&cfg.Dir, "dir", "", "directory to cache tls.crt/tls.key in")
+	flag.StringVar(&cfg.CN, "cn", "", "certificate common name")
+	flag.StringVar(&cfg.DNS, "dns", "", "comma-separated DNS SANs")
 	flag.Parse()
 
-	if *dir == "" || *cn == "" || *dnsCSV == "" {
-		fatal("eks-webhook-cert: -dir, -cn and -dns are required")
+	if err := webhookcert.Run(context.Background(), cfg); err != nil {
+		slog.Error("eks-webhook-cert: " + err.Error())
+		os.Exit(1)
 	}
-	dnsNames := splitCSV(*dnsCSV)
-	if len(dnsNames) == 0 {
-		fatal("eks-webhook-cert: -dns lists no names")
-	}
-
-	certPEM, keyPEM, err := ensureCert(*dir, *cn, dnsNames)
-	if err != nil {
-		fatal("eks-webhook-cert: " + err.Error())
-	}
-	b := base64.StdEncoding.EncodeToString
-	fmt.Printf("%s\t%s\t%s\n", b(certPEM), b(certPEM), b(keyPEM))
-}
-
-// ensureCert returns the cached cert/key under dir, minting and persisting a
-// fresh self-signed pair (for cn + dnsNames) when none is present or readable.
-func ensureCert(dir, cn string, dnsNames []string) (certPEM, keyPEM []byte, err error) {
-	certPath := filepath.Join(dir, "tls.crt")
-	keyPath := filepath.Join(dir, "tls.key")
-
-	if c, cerr := os.ReadFile(certPath); cerr == nil {
-		if k, kerr := os.ReadFile(keyPath); kerr == nil {
-			if _, perr := x509.ParseCertificate(decodeFirst(c)); perr == nil && len(k) > 0 {
-				return c, k, nil
-			}
-		}
-	}
-
-	certPEM, keyPEM, err = generateSelfSigned(cn, dnsNames)
-	if err != nil {
-		return nil, nil, err
-	}
-	if err = os.MkdirAll(dir, 0o700); err != nil {
-		return nil, nil, fmt.Errorf("mkdir %s: %w", dir, err)
-	}
-	if err = os.WriteFile(certPath, certPEM, 0o644); err != nil {
-		return nil, nil, fmt.Errorf("write %s: %w", certPath, err)
-	}
-	if err = os.WriteFile(keyPath, keyPEM, 0o600); err != nil {
-		return nil, nil, fmt.Errorf("write %s: %w", keyPath, err)
-	}
-	return certPEM, keyPEM, nil
-}
-
-// generateSelfSigned mints an ECDSA-P256 self-signed cert valid as both a CA and
-// a server cert, with the given common name and DNS SANs.
-func generateSelfSigned(cn string, dnsNames []string) (certPEM, keyPEM []byte, err error) {
-	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		return nil, nil, fmt.Errorf("generate key: %w", err)
-	}
-	serial, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
-	if err != nil {
-		return nil, nil, fmt.Errorf("serial: %w", err)
-	}
-	now := time.Now().UTC()
-	tmpl := x509.Certificate{
-		SerialNumber:          serial,
-		Subject:               pkix.Name{CommonName: cn},
-		NotBefore:             now.Add(-time.Hour),
-		NotAfter:              now.AddDate(10, 0, 0),
-		KeyUsage:              x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment | x509.KeyUsageCertSign,
-		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
-		BasicConstraintsValid: true,
-		IsCA:                  true,
-		DNSNames:              dnsNames,
-	}
-	der, err := x509.CreateCertificate(rand.Reader, &tmpl, &tmpl, &priv.PublicKey, priv)
-	if err != nil {
-		return nil, nil, fmt.Errorf("create cert: %w", err)
-	}
-	keyDER, err := x509.MarshalECPrivateKey(priv)
-	if err != nil {
-		return nil, nil, fmt.Errorf("marshal key: %w", err)
-	}
-	certPEM = pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der})
-	keyPEM = pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: keyDER})
-	return certPEM, keyPEM, nil
-}
-
-// decodeFirst returns the DER bytes of the first PEM block, or nil.
-func decodeFirst(pemBytes []byte) []byte {
-	blk, _ := pem.Decode(pemBytes)
-	if blk == nil {
-		return nil
-	}
-	return blk.Bytes
-}
-
-func splitCSV(s string) []string {
-	var out []string
-	for p := range strings.SplitSeq(s, ",") {
-		if p = strings.TrimSpace(p); p != "" {
-			out = append(out, p)
-		}
-	}
-	return out
-}
-
-func fatal(msg string) {
-	slog.Error(msg)
-	os.Exit(1)
 }

cmd/eks-webhook-cert/main_test.go

@@ -1,81 +0,0 @@
-package main
-
-import (
-	"crypto/x509"
-	"os"
-	"path/filepath"
-	"testing"
-)
-
-const (
-	testCN  = "aws-load-balancer-webhook-service.kube-system.svc"
-	testDNS = "aws-load-balancer-webhook-service.kube-system.svc.cluster.local"
-)
-
-func parseLeaf(t *testing.T, certPEM []byte) *x509.Certificate {
-	t.Helper()
-	leaf, err := x509.ParseCertificate(decodeFirst(certPEM))
-	if err != nil {
-		t.Fatalf("parse cert: %v", err)
-	}
-	return leaf
-}
-
-func TestEnsureCertMintsServingCert(t *testing.T) {
-	dir := t.TempDir()
-	certPEM, keyPEM, err := ensureCert(dir, testCN, []string{testCN, testDNS})
-	if err != nil {
-		t.Fatalf("ensureCert: %v", err)
-	}
-	if len(keyPEM) == 0 {
-		t.Fatal("empty key PEM")
-	}
-	leaf := parseLeaf(t, certPEM)
-
-	// Both webhook service DNS names must be present, or the apiserver's TLS
-	// dial to the webhook fails SAN verification.
-	for _, want := range []string{testCN, testDNS} {
-		if err := leaf.VerifyHostname(want); err != nil {
-			t.Errorf("SAN %q missing: %v", want, err)
-		}
-	}
-	if !leaf.IsCA {
-		t.Error("cert must be a CA so the same PEM serves as the webhook caBundle")
-	}
-
-	// The single self-signed cert must verify against itself as a root — this is
-	// exactly what the apiserver does with caBundle == the serving cert.
-	roots := x509.NewCertPool()
-	roots.AddCert(leaf)
-	if _, err := leaf.Verify(x509.VerifyOptions{
-		Roots:     roots,
-		DNSName:   testCN,
-		KeyUsages: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
-	}); err != nil {
-		t.Errorf("self-signed cert does not verify as its own CA: %v", err)
-	}
-}
-
-func TestEnsureCertReusesCachedPair(t *testing.T) {
-	dir := t.TempDir()
-	cert1, key1, err := ensureCert(dir, testCN, []string{testCN})
-	if err != nil {
-		t.Fatalf("first ensureCert: %v", err)
-	}
-	cert2, key2, err := ensureCert(dir, testCN, []string{testCN})
-	if err != nil {
-		t.Fatalf("second ensureCert: %v", err)
-	}
-	if string(cert1) != string(cert2) || string(key1) != string(key2) {
-		t.Error("ensureCert regenerated instead of reusing the cached pair; a churning cert re-applies the addon every tick")
-	}
-
-	// The private key must not be world-readable on disk.
-	info, err := os.Stat(filepath.Join(dir, "tls.key"))
-	if err != nil {
-		t.Fatalf("stat key: %v", err)
-	}
-	if info.Mode().Perm()&0o077 != 0 {
-		t.Errorf("tls.key mode %o is group/other-accessible", info.Mode().Perm())
-	}
-}

cmd/installer/main.go

@@ -5,10 +5,10 @@ import (
 	"os"
 	"strings"
 
-	"github.com/mulgadc/spinifex/cmd/installer/autoinstall"
-	"github.com/mulgadc/spinifex/cmd/installer/install"
-	"github.com/mulgadc/spinifex/cmd/installer/ui"
-	_ "github.com/mulgadc/spinifex/internal/fipsboot"
+	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
+	"github.com/mulgadc/spinifex/spinifex/operator/installer/autoinstall"
+	"github.com/mulgadc/spinifex/spinifex/operator/installer/install"
+	"github.com/mulgadc/spinifex/spinifex/operator/installer/ui"
 )
 
 func main() {

cmd/installer/ui/storage_test.go

@@ -1,139 +0,0 @@
-package ui
-
-import (
-	"slices"
-	"strings"
-	"testing"
-
-	"github.com/mulgadc/spinifex/cmd/installer/install"
-)
-
-// diskModel is a storage screen with n unselected disks and ext4 chosen, which
-// is where the wizard starts.
-func diskModel(n int) model {
-	m := model{fsCursor: slices.Index(install.AllFSTypes, install.FSExt4)}
-	for i := range n {
-		m.disks = append(m.disks, install.Disk{
-			Path:              string(rune('a'+i)) + "-disk",
-			Bytes:             200 << 30,
-			LogicalBlockSize:  512,
-			PhysicalBlockSize: 512,
-		})
-	}
-	return m
-}
-
-func rolePaths(cfg install.DiskConfig) map[install.DiskRole]string {
-	out := map[install.DiskRole]string{}
-	for _, rm := range cfg.Roles {
-		out[rm.Role] = rm.Disk.Path
-	}
-	return out
-}
-
-// A single-disk machine should need no storage input at all, so the disk that
-// newModel preselects has to arrive already holding the os role.
-func TestPreselectedDiskIsAValidConfiguration(t *testing.T) {
-	m := newModel([]install.Disk{{Path: "/dev/sda", Bytes: 200 << 30, LogicalBlockSize: 512}}, nil)
-	cfg := m.storage()
-	if err := cfg.Validate(); err != nil {
-		t.Fatalf("the preselected disk must be installable as-is: %v", err)
-	}
-	if cfg.Primary().Path != "/dev/sda" {
-		t.Errorf("Primary() = %q, want the preselected disk", cfg.Primary().Path)
-	}
-}
-
-// Picking disks in order gives the layout an operator almost always wants, so
-// the role key is only needed for the exceptions.
-func TestSelectingDisksAssignsRolesInOrder(t *testing.T) {
-	m := diskModel(3)
-	for i := range 3 {
-		m = m.toggleDisk(i)
-	}
-	got := rolePaths(m.storage())
-	for role, want := range map[install.DiskRole]string{
-		install.RoleOS: "a-disk", install.RoleSpinifex: "b-disk", install.RolePredastore: "c-disk",
-	} {
-		if got[role] != want {
-			t.Errorf("%s = %q, want %q", role, got[role], want)
-		}
-	}
-	if err := m.storage().Validate(); err != nil {
-		t.Errorf("the default assignment must be valid: %v", err)
-	}
-}
-
-// Deselecting has to drop the role with the disk, or every later role shifts
-// onto the wrong drive.
-func TestDeselectingADiskReleasesItsRole(t *testing.T) {
-	m := diskModel(3)
-	for i := range 3 {
-		m = m.toggleDisk(i)
-	}
-	m = m.toggleDisk(1) // drop the spinifex drive
-
-	got := rolePaths(m.storage())
-	if got[install.RoleOS] != "a-disk" || got[install.RolePredastore] != "c-disk" {
-		t.Fatalf("remaining roles moved: %v", got)
-	}
-	if _, ok := got[install.RoleSpinifex]; ok {
-		t.Errorf("the spinifex role should be free again: %v", got)
-	}
-}
-
-// The two-drive predastore layout is only reachable by reassigning, so cycling
-// swaps rather than refusing a role another disk already holds.
-func TestCycleRoleSwapsWithTheDiskThatHoldsIt(t *testing.T) {
-	m := diskModel(2)
-	m = m.toggleDisk(0).toggleDisk(1)
-	// b-disk: spinifex → predastore, which no disk holds, so no swap.
-	m = m.cycleRole(1)
-
-	got := rolePaths(m.storage())
-	if got[install.RoleOS] != "a-disk" || got[install.RolePredastore] != "b-disk" {
-		t.Fatalf("roles = %v, want os on a-disk and predastore on b-disk", got)
-	}
-
-	// Cycling past the end wraps onto os, which a-disk holds, so they trade.
-	m = m.cycleRole(1)
-	got = rolePaths(m.storage())
-	if got[install.RoleOS] != "b-disk" || got[install.RolePredastore] != "a-disk" {
-		t.Fatalf("roles = %v, want the two disks to have swapped", got)
-	}
-	if err := m.storage().Validate(); err != nil {
-		t.Errorf("a swap must always leave a valid assignment: %v", err)
-	}
-}
-
-// ZFS pairs mirrors by selection order and has no roles to assign.
-func TestStorageLeavesRolesUnsetOnZFS(t *testing.T) {
-	m := diskModel(2)
-	m.fsCursor = slices.Index(install.AllFSTypes, install.FSZFSRAID1)
-	m = m.toggleDisk(0).toggleDisk(1)
-
-	cfg := m.storage()
-	if len(cfg.Roles) != 0 {
-		t.Errorf("Roles = %v, want none on a pool", cfg.Roles)
-	}
-	if !slices.Equal(cfg.Paths(), []string{"a-disk", "b-disk"}) {
-		t.Errorf("Paths() = %v, want the selection order preserved", cfg.Paths())
-	}
-}
-
-// A three-drive selection looks like an array and is not one, so the mapping
-// and the absence of redundancy both have to be on screen before the erase.
-func TestConfirmScreenStatesTheLayoutAndTheRisk(t *testing.T) {
-	m := diskModel(3)
-	m.height = 40
-	for i := range 3 {
-		m = m.toggleDisk(i)
-	}
-	got := m.viewDiskConfirm(100)
-
-	for _, want := range []string{"/var/lib/spinifex/predastore", "c-disk", "losing one loses"} {
-		if !strings.Contains(got, want) {
-			t.Errorf("confirm screen is missing %q:\n%s", want, got)
-		}
-	}
-}

cmd/lb-agent/main.go

@@ -21,7 +21,7 @@ import (
 	"github.com/mulgadc/bluebottle/pkg/otelsetup"
 	"github.com/mulgadc/spinifex/spinifex/lbagent"
 
-	_ "github.com/mulgadc/spinifex/internal/fipsboot"
+	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
 )
 
 func main() {

cmd/rds-agent/agent.go

@@ -1,423 +0,0 @@
-package main
-
-import (
-	"bufio"
-	"context"
-	"errors"
-	"fmt"
-	"log/slog"
-	"net/url"
-	"os"
-	"strconv"
-	"strings"
-	"time"
-
-	"github.com/mulgadc/spinifex/internal/gwsign"
-	"github.com/mulgadc/spinifex/internal/rdsgw"
-	handlers_rds "github.com/mulgadc/spinifex/spinifex/handlers/rds"
-	"github.com/mulgadc/spinifex/spinifex/otelsetup"
-)
-
-// Overridable via -ldflags "-X main.version=...".
-var version = "dev"
-
-// The gateway resolves the authoritative DB instance from the request's
-// credentials, so DBInstanceIdentifier is an assertion to be checked, not
-// trusted.
-type identity struct {
-	DBInstanceIdentifier string
-	AgentVersion         string
-	EngineVersion        string
-}
-
-// Every method is a SigV4-signed Query request, so the NATS bus stays
-// host-internal.
-type controlPlane interface {
-	Register(ctx context.Context, id identity) (*handlers_rds.RegisterDBInstanceOutput, error)
-	SubmitState(ctx context.Context, id identity, health handlers_rds.EngineHealth, message string) (*handlers_rds.SubmitDBStateChangeOutput, error)
-	// Returns Mode=initialize with the master password for as long as a payload
-	// staged for this VM generation is unacknowledged, and Mode=attach after.
-	GetBootstrapConfig(ctx context.Context, id identity) (*handlers_rds.GetDBBootstrapConfigOutput, error)
-	// Reports that PostgreSQL durably applied the staged password, which is what
-	// lets the control plane destroy it.
-	AcknowledgeBootstrap(ctx context.Context, id identity, pending *pendingBootstrap) error
-	PollCommands(ctx context.Context, id identity, replies []handlers_rds.CommandReply, wait time.Duration) ([]handlers_rds.Command, error)
-}
-
-// Bounds a register, heartbeat or bootstrap request. The long poll sets its own
-// deadline from the wait it asked the gateway to hold.
-const callTimeout = 15 * time.Second
-
-// Keeps the poll's deadline past the requested wait, so a gateway answering at
-// the end of its window is not cut off by the client.
-const pollSlack = 10 * time.Second
-
-type gatewayControlPlane struct {
-	client *rdsgw.Client
-}
-
-var _ controlPlane = (*gatewayControlPlane)(nil)
-
-// Signs with the instance-role credentials the SDK chain resolves from IMDS,
-// against the pinned gateway CA.
-func newGatewayControlPlane(cfg config) (*gatewayControlPlane, error) {
-	signer, err := gwsign.NewIMDS(context.Background(), cfg.Region)
-	if err != nil {
-		return nil, fmt.Errorf("build IMDS signer: %w", err)
-	}
-	// The client timeout is the ceiling for the longest call, the long poll;
-	// shorter calls carry their own deadline.
-	client, err := rdsgw.New(cfg.GatewayURL, cfg.GatewayCA, signer, cfg.Region, cfg.PollWait+pollSlack)
-	if err != nil {
-		return nil, err
-	}
-	return &gatewayControlPlane{client: client}, nil
-}
-
-func (g *gatewayControlPlane) Register(ctx context.Context, id identity) (*handlers_rds.RegisterDBInstanceOutput, error) {
-	params := url.Values{}
-	setIfPresent(params, "DBInstanceIdentifier", id.DBInstanceIdentifier)
-	setIfPresent(params, "AgentVersion", id.AgentVersion)
-	setIfPresent(params, "EngineVersion", id.EngineVersion)
-
-	ctx, cancel := context.WithTimeout(ctx, callTimeout)
-	defer cancel()
-
-	var out handlers_rds.RegisterDBInstanceOutput
-	if err := g.client.Call(ctx, "RegisterDBInstance", params, &out); err != nil {
-		return nil, err
-	}
-	return &out, nil
-}
-
-func (g *gatewayControlPlane) SubmitState(ctx context.Context, id identity, health handlers_rds.EngineHealth, message string) (*handlers_rds.SubmitDBStateChangeOutput, error) {
-	params := url.Values{"EngineHealth": {string(health)}}
-	setIfPresent(params, "DBInstanceIdentifier", id.DBInstanceIdentifier)
-	setIfPresent(params, "EngineVersion", id.EngineVersion)
-	setIfPresent(params, "Message", message)
-
-	ctx, cancel := context.WithTimeout(ctx, callTimeout)
-	defer cancel()
-
-	var out handlers_rds.SubmitDBStateChangeOutput
-	if err := g.client.Call(ctx, "SubmitDBStateChange", params, &out); err != nil {
-		return nil, err
-	}
-	return &out, nil
-}
-
-func (g *gatewayControlPlane) GetBootstrapConfig(ctx context.Context, id identity) (*handlers_rds.GetDBBootstrapConfigOutput, error) {
-	params := url.Values{}
-	setIfPresent(params, "DBInstanceIdentifier", id.DBInstanceIdentifier)
-
-	ctx, cancel := context.WithTimeout(ctx, callTimeout)
-	defer cancel()
-
-	var out handlers_rds.GetDBBootstrapConfigOutput
-	if err := g.client.Call(ctx, "GetDBBootstrapConfig", params, &out); err != nil {
-		return nil, err
-	}
-	return &out, nil
-}
-
-func (g *gatewayControlPlane) AcknowledgeBootstrap(ctx context.Context, id identity, pending *pendingBootstrap) error {
-	params := url.Values{
-		"PayloadId":    {pending.payloadID},
-		"VMGeneration": {strconv.FormatInt(pending.vmGeneration, 10)},
-	}
-	setIfPresent(params, "DBInstanceIdentifier", id.DBInstanceIdentifier)
-	setIfPresent(params, "DataVolumeId", pending.dataVolumeID)
-
-	ctx, cancel := context.WithTimeout(ctx, callTimeout)
-	defer cancel()
-
-	var out handlers_rds.AcknowledgeDBBootstrapOutput
-	if err := g.client.Call(ctx, "AcknowledgeDBBootstrap", params, &out); err != nil {
-		return err
-	}
-	if !out.Acknowledged {
-		return fmt.Errorf("the control plane did not acknowledge bootstrap payload %s", pending.payloadID)
-	}
-	return nil
-}
-
-// Declared here so the in-guest binary does not link the server side of the API.
-type pollDBCommandsOutput struct {
-	Commands []handlers_rds.Command `xml:"Commands>member"`
-}
-
-func (g *gatewayControlPlane) PollCommands(ctx context.Context, id identity, replies []handlers_rds.CommandReply, wait time.Duration) ([]handlers_rds.Command, error) {
-	params := url.Values{"WaitTimeSeconds": {strconv.FormatInt(int64(wait.Seconds()), 10)}}
-	setIfPresent(params, "DBInstanceIdentifier", id.DBInstanceIdentifier)
-	// Replies ride the poll rather than a separate action, so replying and
-	// asking for the next command are one round trip.
-	for i, reply := range replies {
-		member := fmt.Sprintf("Replies.member.%d.", i+1)
-		params.Set(member+"CommandId", reply.CommandID)
-		params.Set(member+"Status", reply.Status)
-		setIfPresent(params, member+"Message", reply.Message)
-	}
-
-	ctx, cancel := context.WithTimeout(ctx, wait+pollSlack)
-	defer cancel()
-
-	var out pollDBCommandsOutput
-	if err := g.client.Call(ctx, "PollDBCommands", params, &out); err != nil {
-		return nil, err
-	}
-	return out.Commands, nil
-}
-
-// Only sets a parameter that has a value, so the gateway can tell "no
-// assertion" from "asserted as blank".
-func setIfPresent(params url.Values, key, value string) {
-	if value != "" {
-		params.Set(key, value)
-	}
-}
-
-type Agent struct {
-	cfg             config
-	id              identity
-	cp              controlPlane
-	probe           *engineProbe
-	engine          engine
-	handoffWriter   func(string, *handlers_rds.GetDBBootstrapConfigOutput) error
-	dataMountWaiter func(context.Context, string, string) error
-
-	// Set by bootstrap when the fetch replayed a staged payload; nil leaves the
-	// acknowledgement step a no-op, which is every attach boot.
-	pending *pendingBootstrap
-
-	hb    *heartbeater
-	cmd   *commander
-	guard *paramGuard
-}
-
-// Assembles from already-built parts, so tests can pass fakes; New builds the
-// production control plane and delegates here.
-func newAgent(cfg config, cp controlPlane, probe *engineProbe) (*Agent, error) {
-	if cfg.MountsFile == "" {
-		cfg.MountsFile = defaultMountsFile
-	}
-	id := identity{
-		DBInstanceIdentifier: cfg.DBInstanceIdentifier,
-		AgentVersion:         version,
-		EngineVersion:        cfg.EngineVersion,
-	}
-	a := &Agent{
-		cfg: cfg, id: id, cp: cp, probe: probe,
-		handoffWriter: writeHandoff, dataMountWaiter: waitForDataMount,
-	}
-	eng, err := newEngine(cfg, execCommandRunner, execSessionRunner, probe)
-	if err != nil {
-		return nil, err
-	}
-	a.engine = eng
-	a.hb = newHeartbeater(cp, probe, a.engine, handlers_rds.HeartbeatInterval)
-	a.cmd = newCommander(cp, newCommandRegistry(a.engine, newGuestStorage(cfg, execCommandRunner)), cfg.PollWait)
-	a.guard = newParamGuard(a.engine, probe, cp)
-	return a, nil
-}
-
-// Does not wait for IMDS: the register loop rides out a datapath still coming up.
-func New(cfg config) (*Agent, error) {
-	if cfg.GatewayURL == "" {
-		return nil, fmt.Errorf("no gateway URL configured (RDS_GATEWAY_URL)")
-	}
-	cp, err := newGatewayControlPlane(cfg)
-	if err != nil {
-		return nil, err
-	}
-	probe, err := newProbe(cfg, execProbeRunner)
-	if err != nil {
-		return nil, err
-	}
-	return newAgent(cfg, cp, probe)
-}
-
-func (a *Agent) Run(ctx context.Context) error {
-	// Named before the first dial: when register cannot reach the gateway, the
-	// address it is dialing is what separates a mgmt NIC that came up without one
-	// from a control plane that is genuinely down.
-	slog.Info("rds-agent: starting",
-		"gatewayURL", a.cfg.GatewayURL, "dbInstanceIdentifier", a.id.DBInstanceIdentifier,
-		"agentVersion", a.id.AgentVersion)
-
-	// Registration comes first: its response is the agent's identity.
-	if err := a.register(ctx); err != nil {
-		return err
-	}
-	a.hb.id, a.cmd.id, a.guard.id = a.id, a.id, a.id
-
-	// Ahead of the handoff, so rds-init never unblocks and no datadir is touched.
-	// An agent running on the wrong image would initialise one engine over
-	// another's data, coming up healthy and empty beside data nothing references.
-	if err := a.refuseEngineMismatch(ctx); err != nil {
-		return err
-	}
-
-	// Beating before the bootstrap keeps a stuck boot visible as a live VM with
-	// a down engine rather than as silence.
-	go a.hb.Run(ctx)
-
-	if err := a.bootstrap(ctx); err != nil {
-		return err
-	}
-
-	// The handoff must land before this wait: rds-datadir needs it to identify
-	// and authorize the volume. Commands and the parameter guard wait because
-	// their durable state belongs on that mount, never on the disposable boot disk.
-	if err := a.dataMountWaiter(ctx, a.cfg.MountsFile, a.cfg.DataMount); err != nil {
-		// A shutdown cancels this wait; main treats the wrapped context.Canceled
-		// as a clean stop, exactly as it does for register and bootstrap above.
-		return fmt.Errorf("wait for data mount %s: %w", a.cfg.DataMount, err)
-	}
-
-	// The receipt it waits on lives on that mount, so this cannot run any earlier.
-	// A cancelled wait is a clean stop here too.
-	if err := a.acknowledgeBootstrap(ctx); err != nil {
-		return err
-	}
-
-	// Directives are only meaningful against a bootstrapped, mounted engine.
-	go a.cmd.Run(ctx)
-
-	// Started after the handoff, so the window it measures covers the engine's
-	// own start rather than the time rds-init spent waiting for this agent.
-	go a.guard.Run(ctx)
-
-	<-ctx.Done()
-	return nil
-}
-
-// The engine cloud-init says this VM was launched as, against the engine the
-// image bakes. An empty expectation is no assertion rather than a disagreement:
-// a VM launched before the control plane emitted RDS_ENGINE carries none.
-func (a *Agent) refuseEngineMismatch(ctx context.Context) error {
-	expected := strings.ToLower(strings.TrimSpace(a.cfg.Engine))
-	if expected == "" || expected == a.cfg.BakedEngine {
-		return nil
-	}
-
-	message := fmt.Sprintf("this VM was launched as engine %q but its image bakes %q; refusing to bootstrap",
-		expected, a.cfg.BakedEngine)
-	slog.ErrorContext(ctx, "rds-agent: "+message)
-	// Reported before returning, so the control plane learns why the instance
-	// never came up rather than only that it never did.
-	if _, err := a.cp.SubmitState(ctx, a.id, handlers_rds.EngineHealthUnhealthy, message); err != nil {
-		slog.ErrorContext(ctx, "rds-agent: reporting the engine mismatch failed", "err", err)
-	}
-	return errors.New(message)
-}
-
-const dataMountPollInterval = time.Second
-
-// waitForDataMount blocks the stateful agent loops until the kernel reports the
-// configured data mount. Registration, heartbeat, and bootstrap run before it.
-func waitForDataMount(ctx context.Context, mountsFile, target string) error {
-	ticker := time.NewTicker(dataMountPollInterval)
-	defer ticker.Stop()
-
-	for {
-		mounted, err := mountTableContains(mountsFile, target)
-		if err != nil {
-			slog.WarnContext(ctx, "rds-agent: could not read mount table while waiting for data volume",
-				"mountsFile", mountsFile, "dataMount", target, "err", err)
-		} else if mounted {
-			slog.InfoContext(ctx, "rds-agent: data volume mount is ready", "dataMount", target)
-			return nil
-		}
-
-		select {
-		case <-ctx.Done():
-			return ctx.Err()
-		case <-ticker.C:
-		}
-	}
-}
-
-func mountTableContains(path, target string) (bool, error) {
-	f, err := os.Open(path)
-	if err != nil {
-		return false, err
-	}
-	defer f.Close()
-
-	scanner := bufio.NewScanner(f)
-	for scanner.Scan() {
-		fields := strings.Fields(scanner.Text())
-		if len(fields) >= 2 && unescapeMountField(fields[1]) == target {
-			return true, nil
-		}
-	}
-	if err := scanner.Err(); err != nil {
-		return false, err
-	}
-	return false, nil
-}
-
-// Linux mount tables encode whitespace and backslashes as octal escapes.
-func unescapeMountField(field string) string {
-	replacer := strings.NewReplacer(`\134`, `\`, `\040`, " ", `\011`, "\t", `\012`, "\n")
-	return replacer.Replace(field)
-}
-
-// Boot-retry bounds. Tight to start, since the usual cause is a control plane
-// still creating this instance's record, and capped so an outage does not turn
-// a booting fleet into a retry storm.
-const (
-	retryMin = 1 * time.Second
-	retryMax = 30 * time.Second
-
-	// With the production backoff, attempt five is about 15 seconds into the
-	// failure and still precedes the first 30-second heartbeat.
-	retryErrorAttempt = 5
-)
-
-// Wrapping an error in this stops retryObserved. For the failures the control
-// plane decides from its own record, no retry can change the answer, and looping
-// on one only keeps the caller blocked.
-var errRetryTerminal = errors.New("terminal failure")
-
-// Never gives up on its own: an agent that stopped trying would leave the
-// control plane with no signal at all.
-func retry(ctx context.Context, what string, fn func(context.Context) error) error {
-	return retryObserved(ctx, what, fn, nil)
-}
-
-// onFailure lets boot-critical callers publish the latest error while the retry
-// remains blocked. It must not block because it runs on the retry path itself.
-func retryObserved(ctx context.Context, what string, fn func(context.Context) error, onFailure func(error)) error {
-	delay := retryMin
-	for attempt := 1; ; attempt++ {
-		err := fn(ctx)
-		if err == nil {
-			return nil
-		}
-		if ctx.Err() != nil {
-			return fmt.Errorf("%s: %w", what, ctx.Err())
-		}
-		if onFailure != nil {
-			onFailure(err)
-		}
-		if errors.Is(err, errRetryTerminal) {
-			slog.ErrorContext(ctx, "rds-agent: "+what+" failed terminally, not retrying", "err", err)
-			return fmt.Errorf("%s: %w", what, err)
-		}
-		if attempt >= retryErrorAttempt {
-			slog.ErrorContext(ctx, "rds-agent: "+what+" still failing, retrying",
-				"attempt", attempt, "retry_in_ms", otelsetup.Millis(delay), "err", err)
-		} else {
-			slog.WarnContext(ctx, "rds-agent: "+what+" failed, retrying",
-				"attempt", attempt, "retry_in_ms", otelsetup.Millis(delay), "err", err)
-		}
-
-		select {
-		case <-ctx.Done():
-			return fmt.Errorf("%s: %w", what, ctx.Err())
-		case <-time.After(delay):
-		}
-		delay = min(delay*2, retryMax)
-	}
-}

cmd/rds-agent/agent_test.go

@@ -1,873 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"net/http"
-	"net/http/httptest"
-	"os"
-	"path/filepath"
-	"slices"
-	"strings"
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/mulgadc/spinifex/internal/gwsign"
-	"github.com/mulgadc/spinifex/internal/rdsgw"
-	"github.com/mulgadc/spinifex/spinifex/awserrors"
-	gateway_rds "github.com/mulgadc/spinifex/spinifex/gateway/rds"
-	handlers_rds "github.com/mulgadc/spinifex/spinifex/handlers/rds"
-	"github.com/mulgadc/spinifex/spinifex/utils"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-// fakeControlPlane is a scriptable controlPlane. Every call records what the
-// agent sent, so a test asserts on the request as well as the reaction.
-type fakeControlPlane struct {
-	mu sync.Mutex
-
-	registerOut  *handlers_rds.RegisterDBInstanceOutput
-	registerErrs []error
-	registerReqs []identity
-
-	bootstrapOut  *handlers_rds.GetDBBootstrapConfigOutput
-	bootstrapErrs []error
-	bootstrapReqs []identity
-	// Scripted responses ahead of bootstrapOut, so a test can answer the first
-	// fetch differently from the ones the agent retries with.
-	bootstrapQueue []*handlers_rds.GetDBBootstrapConfigOutput
-
-	ackErrs []error
-	ackReqs []pendingBootstrap
-
-	states []submittedState
-
-	pollReplies [][]handlers_rds.CommandReply
-	pollQueue   [][]handlers_rds.Command
-	pollErr     error
-	polled      chan struct{}
-}
-
-type submittedState struct {
-	id      identity
-	health  handlers_rds.EngineHealth
-	message string
-}
-
-var _ controlPlane = (*fakeControlPlane)(nil)
-
-func newFakeControlPlane() *fakeControlPlane {
-	return &fakeControlPlane{
-		registerOut: &handlers_rds.RegisterDBInstanceOutput{
-			DBInstanceIdentifier: "db-resolved", HeartbeatIntervalSeconds: 30,
-		},
-		polled: make(chan struct{}, 64),
-	}
-}
-
-// nextErr pops the next scripted error, so a test can fail a call n times and
-// then let it succeed.
-func nextErr(errs *[]error) error {
-	if len(*errs) == 0 {
-		return nil
-	}
-	err := (*errs)[0]
-	*errs = (*errs)[1:]
-	return err
-}
-
-func (f *fakeControlPlane) Register(_ context.Context, id identity) (*handlers_rds.RegisterDBInstanceOutput, error) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.registerReqs = append(f.registerReqs, id)
-	if err := nextErr(&f.registerErrs); err != nil {
-		return nil, err
-	}
-	return f.registerOut, nil
-}
-
-func (f *fakeControlPlane) SubmitState(_ context.Context, id identity, health handlers_rds.EngineHealth, message string) (*handlers_rds.SubmitDBStateChangeOutput, error) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.states = append(f.states, submittedState{id: id, health: health, message: message})
-	// Zero means "keep the cadence you have", so a test's fast interval is not
-	// reset by every beat.
-	return &handlers_rds.SubmitDBStateChangeOutput{Acknowledged: true}, nil
-}
-
-func (f *fakeControlPlane) GetBootstrapConfig(_ context.Context, id identity) (*handlers_rds.GetDBBootstrapConfigOutput, error) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.bootstrapReqs = append(f.bootstrapReqs, id)
-	if err := nextErr(&f.bootstrapErrs); err != nil {
-		return nil, err
-	}
-	if len(f.bootstrapQueue) > 0 {
-		out := f.bootstrapQueue[0]
-		f.bootstrapQueue = f.bootstrapQueue[1:]
-		return out, nil
-	}
-	return f.bootstrapOut, nil
-}
-
-func (f *fakeControlPlane) AcknowledgeBootstrap(_ context.Context, _ identity, pending *pendingBootstrap) error {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.ackReqs = append(f.ackReqs, *pending)
-	return nextErr(&f.ackErrs)
-}
-
-func (f *fakeControlPlane) PollCommands(ctx context.Context, _ identity, replies []handlers_rds.CommandReply, _ time.Duration) ([]handlers_rds.Command, error) {
-	f.mu.Lock()
-	f.pollReplies = append(f.pollReplies, slices.Clone(replies))
-	err := f.pollErr
-	var out []handlers_rds.Command
-	if len(f.pollQueue) > 0 {
-		out, f.pollQueue = f.pollQueue[0], f.pollQueue[1:]
-	}
-	f.mu.Unlock()
-
-	select {
-	case f.polled <- struct{}{}:
-	default:
-	}
-	if err != nil {
-		return nil, err
-	}
-	if len(out) > 0 {
-		return out, nil
-	}
-	// An idle window: block until the agent hangs up, as the gateway's long poll
-	// does, rather than spinning the caller's loop.
-	<-ctx.Done()
-	return nil, ctx.Err()
-}
-
-func (f *fakeControlPlane) ackRequests() []pendingBootstrap {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	return slices.Clone(f.ackReqs)
-}
-
-func (f *fakeControlPlane) snapshotStates() []submittedState {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	return append([]submittedState(nil), f.states...)
-}
-
-func (f *fakeControlPlane) snapshotReplies() [][]handlers_rds.CommandReply {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	out := make([][]handlers_rds.CommandReply, len(f.pollReplies))
-	for i := range f.pollReplies {
-		out[i] = slices.Clone(f.pollReplies[i])
-	}
-	return out
-}
-
-// testConfig stamps the engine a real rds-postgres image bakes, so the agent
-// resolves the same guest layout it would in a guest, and points its file output
-// at a temp dir.
-func testConfig(t *testing.T) config {
-	t.Helper()
-	cfg := testLoadConfig(t, enginePostgres)
-	cfg.GatewayURL = "https://gw.test"
-	cfg.HandoffDir = filepath.Join(t.TempDir(), "spinifex-rds")
-	cfg.PollWait = time.Second
-	return cfg
-}
-
-// newTestAgent builds the agent over a probe the test drives directly.
-func newTestAgent(t *testing.T, cfg config, cp controlPlane, run probeRunner) *Agent {
-	t.Helper()
-	a, err := newAgent(cfg, cp, newPostgresProbe(cfg, run))
-	if err != nil {
-		t.Fatalf("newAgent: %v", err)
-	}
-	return a
-}
-
-// staticProbe is a probeRunner that always reports the same exit code.
-func staticProbe(code int) probeRunner {
-	return func(context.Context, string, ...string) (int, string, error) { return code, "", nil }
-}
-
-func bootstrapOutput(password *string) *handlers_rds.GetDBBootstrapConfigOutput {
-	mode := handlers_rds.BootstrapModeAttach
-	if password != nil {
-		mode = handlers_rds.BootstrapModeInitialize
-	}
-	return &handlers_rds.GetDBBootstrapConfigOutput{
-		Mode:                 mode,
-		DBInstanceIdentifier: "db-resolved",
-		Engine:               "postgres",
-		MasterUsername:       "master",
-		MasterUserPassword:   password,
-		Port:                 5432,
-		ListenAddress:        testListenAddress,
-		ClientCIDR:           testClientCIDR,
-		DataVolumeID:         "vol-data-01",
-		DataVolumeSerial:     "voldata01",
-		VMGeneration:         1,
-		PayloadID:            testPayloadID,
-		BootstrapPending:     password != nil,
-	}
-}
-
-const testPayloadID = "bp-0123456789abcdef"
-
-// The customer ENI address the engine binds, and the VPC range its client
-// authentication admits. writeHandoff refuses a config without either.
-const (
-	testListenAddress = "10.0.1.20"
-	testClientCIDR    = "10.0.0.0/16"
-)
-
-// Writes the completion receipt rds-init leaves behind, so the acknowledgement
-// step finds what a finished initialization would have produced.
-func writeReceipt(t *testing.T, a *Agent, payloadID, dbInstanceIdentifier string) {
-	t.Helper()
-	path := a.receiptPath()
-	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
-		t.Fatalf("mkdir receipt dir: %v", err)
-	}
-	body := fmt.Sprintf("%s=%s\n%s=%s\n", receiptPayload, payloadID, receiptDBID, dbInstanceIdentifier)
-	if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
-		t.Fatalf("write receipt: %v", err)
-	}
-}
-
-// runAgent runs the agent until its bootstrap has landed, then cancels. It
-// returns once Run has exited so no goroutine outlives the test.
-func runAgent(t *testing.T, a *Agent) error {
-	t.Helper()
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-	defer cancel()
-
-	done := make(chan error, 1)
-	go func() { done <- a.Run(ctx) }()
-
-	waitFor(t, func() bool {
-		_, err := os.Stat(filepath.Join(a.cfg.HandoffDir, handoffEnvFile))
-		return err == nil
-	}, "handoff file to be written")
-
-	cancel()
-	select {
-	case err := <-done:
-		// The cancellation above is this helper's own, so Run reporting it is the
-		// expected clean stop rather than a failure, exactly as main treats it.
-		if errors.Is(err, context.Canceled) {
-			return nil
-		}
-		return err
-	case <-time.After(5 * time.Second):
-		t.Fatal("Run did not exit after cancellation")
-		return nil
-	}
-}
-
-// waitFor polls cond until it holds or the test times out.
-func waitFor(t *testing.T, cond func() bool, what string) {
-	t.Helper()
-	deadline := time.Now().Add(5 * time.Second)
-	for time.Now().Before(deadline) {
-		if cond() {
-			return
-		}
-		time.Sleep(5 * time.Millisecond)
-	}
-	t.Fatalf("timed out waiting for %s", what)
-}
-
-func TestRun_RegistersThenDeliversBootstrap(t *testing.T) {
-	password := "s3cret"
-	cp := newFakeControlPlane()
-	cp.bootstrapOut = bootstrapOutput(&password)
-
-	cfg := testConfig(t)
-	a := newTestAgent(t, cfg, cp, staticProbe(0))
-	if err := runAgent(t, a); err != nil {
-		t.Fatalf("Run: %v", err)
-	}
-
-	if len(cp.registerReqs) != 1 {
-		t.Fatalf("registered %d times, want 1", len(cp.registerReqs))
-	}
-	// The agent had no configured identifier, so the gateway's resolution is
-	// what every later call must carry.
-	if got := cp.bootstrapReqs[0].DBInstanceIdentifier; got != "db-resolved" {
-		t.Errorf("bootstrap sent identifier %q, want the registered db-resolved", got)
-	}
-
-	env := readFile(t, filepath.Join(cfg.HandoffDir, handoffEnvFile))
-	if !strings.Contains(env, "RDS_MODE='initialize'") || !strings.Contains(env, "RDS_MASTER_PASSWORD='s3cret'") {
-		t.Errorf("handoff env = %q, want initialize mode carrying the password", env)
-	}
-	// The probe follows the port the control plane assigned, not the default.
-	if got := a.probe.port.Load(); got != 5432 {
-		t.Errorf("probe port = %d, want 5432", got)
-	}
-}
-
-// A reboot re-fetches in attach mode. The agent must write that payload as it
-// stands rather than refusing it or inventing a password.
-func TestRun_AttachModeNeedsNoPassword(t *testing.T) {
-	cp := newFakeControlPlane()
-	cp.bootstrapOut = bootstrapOutput(nil)
-
-	cfg := testConfig(t)
-	if err := runAgent(t, newTestAgent(t, cfg, cp, staticProbe(0))); err != nil {
-		t.Fatalf("Run: %v", err)
-	}
-
-	env := readFile(t, filepath.Join(cfg.HandoffDir, handoffEnvFile))
-	if !strings.Contains(env, "RDS_MODE='attach'") {
-		t.Errorf("handoff env = %q, want attach mode", env)
-	}
-	if strings.Contains(env, "RDS_MASTER_PASSWORD") {
-		t.Errorf("handoff env = %q, want no password key at all in attach mode", env)
-	}
-}
-
-// The record may not exist yet when a freshly launched VM first calls, so both
-// boot-critical calls have to ride out failures instead of exiting.
-func TestRun_RetriesRegisterAndBootstrap(t *testing.T) {
-	cp := newFakeControlPlane()
-	cp.bootstrapOut = bootstrapOutput(nil)
-	cp.registerErrs = []error{errors.New("DBInstanceNotFound")}
-	cp.bootstrapErrs = []error{errors.New("ServerInternal")}
-
-	cfg := testConfig(t)
-	if err := runAgent(t, newTestAgent(t, cfg, cp, staticProbe(0))); err != nil {
-		t.Fatalf("Run: %v", err)
-	}
-
-	if len(cp.registerReqs) != 2 {
-		t.Errorf("register attempts = %d, want 2 (one failure, one success)", len(cp.registerReqs))
-	}
-	if len(cp.bootstrapReqs) != 2 {
-		t.Errorf("bootstrap attempts = %d, want 2 (one failure, one success)", len(cp.bootstrapReqs))
-	}
-}
-
-// The fetch mutates nothing, so a handoff that cannot be written is retried
-// against the payload already in hand rather than costing a second fetch.
-func TestBootstrap_RetriesHandoffWithoutRefetching(t *testing.T) {
-	cp := newFakeControlPlane()
-	password := "staged-secret"
-	cp.bootstrapOut = bootstrapOutput(&password)
-	cfg := testConfig(t)
-	a := newTestAgent(t, cfg, cp, staticProbe(0))
-
-	writes := 0
-	a.handoffWriter = func(_ string, got *handlers_rds.GetDBBootstrapConfigOutput) error {
-		writes++
-		if got.MasterUserPassword == nil || *got.MasterUserPassword != password {
-			t.Fatalf("handoff attempt %d lost the initialize password", writes)
-		}
-		if writes == 1 {
-			return errors.New("temporary tmpfs write error")
-		}
-		return nil
-	}
-
-	if err := a.bootstrap(t.Context()); err != nil {
-		t.Fatalf("bootstrap: %v", err)
-	}
-	if len(cp.bootstrapReqs) != 1 {
-		t.Errorf("bootstrap fetches = %d, want 1", len(cp.bootstrapReqs))
-	}
-	if writes != 2 {
-		t.Errorf("handoff writes = %d, want 2", writes)
-	}
-	if a.pending == nil || a.pending.payloadID != testPayloadID {
-		t.Errorf("pending bootstrap = %+v, want the staged payload %s", a.pending, testPayloadID)
-	}
-}
-
-// A daemon that predates the encrypted payload answers initialize with nothing
-// to initialise with. Writing that handoff would let rds-init run initdb with an
-// empty master password, so it is retried until an upgraded node answers.
-func TestBootstrap_RetriesInitializeWithNoPassword(t *testing.T) {
-	cp := newFakeControlPlane()
-	empty := ""
-	password := "staged-secret"
-	cp.bootstrapQueue = []*handlers_rds.GetDBBootstrapConfigOutput{{
-		Mode: handlers_rds.BootstrapModeInitialize, DBInstanceIdentifier: "db-resolved",
-		MasterUsername: "master", MasterUserPassword: &empty,
-	}}
-	cp.bootstrapOut = bootstrapOutput(&password)
-	cfg := testConfig(t)
-	a := newTestAgent(t, cfg, cp, staticProbe(0))
-
-	var handed []*handlers_rds.GetDBBootstrapConfigOutput
-	a.handoffWriter = func(_ string, got *handlers_rds.GetDBBootstrapConfigOutput) error {
-		handed = append(handed, got)
-		return nil
-	}
-
-	if err := a.bootstrap(t.Context()); err != nil {
-		t.Fatalf("bootstrap: %v", err)
-	}
-	if len(handed) != 1 {
-		t.Fatalf("handoff writes = %d, want 1 once a usable payload arrived", len(handed))
-	}
-	if handed[0].MasterUserPassword == nil || *handed[0].MasterUserPassword != password {
-		t.Error("the agent wrote a handoff for a fetch that carried no master password")
-	}
-}
-
-func TestAcknowledgeBootstrap_WaitsForTheReceiptThenRetiresIt(t *testing.T) {
-	cp := newFakeControlPlane()
-	cfg := testConfig(t)
-	cfg.DataMount = t.TempDir()
-	a := newTestAgent(t, cfg, cp, staticProbe(0))
-	a.id = identity{DBInstanceIdentifier: "db-resolved"}
-	a.pending = &pendingBootstrap{payloadID: testPayloadID, vmGeneration: 1, dataVolumeID: "vol-data-01"}
-
-	// rds-init runs after the agent registers, so the receipt is absent when the
-	// acknowledgement step first looks and appears some way into the boot.
-	if err := a.checkBootstrapReceipt(a.pending); err == nil {
-		t.Fatal("a missing receipt must not read as a completed bootstrap")
-	}
-	writeReceipt(t, a, testPayloadID, "db-resolved")
-
-	if err := a.acknowledgeBootstrap(t.Context()); err != nil {
-		t.Fatalf("acknowledgeBootstrap: %v", err)
-	}
-	if len(cp.ackRequests()) != 1 {
-		t.Fatalf("acknowledgements = %d, want 1", len(cp.ackRequests()))
-	}
-	if got := cp.ackRequests()[0]; got != *a.pending {
-		t.Errorf("acknowledged %+v, want %+v", got, *a.pending)
-	}
-	if _, err := os.Stat(a.receiptPath()); !os.IsNotExist(err) {
-		t.Error("the receipt must be removed once the record holds the audit trail")
-	}
-}
-
-// The receipt rides along in every snapshot of the data volume, so a restored
-// instance's volume carries the source instance's receipt. Acknowledging on one
-// would destroy the ciphertext this instance still needs.
-func TestAcknowledgeBootstrap_IgnoresAForeignReceipt(t *testing.T) {
-	tests := map[string]struct{ payloadID, dbID string }{
-		"another payload":  {payloadID: "bp-somebody-else", dbID: "db-resolved"},
-		"another instance": {payloadID: testPayloadID, dbID: "db-the-snapshot-source"},
-	}
-
-	for name, tc := range tests {
-		t.Run(name, func(t *testing.T) {
-			cp := newFakeControlPlane()
-			cfg := testConfig(t)
-			cfg.DataMount = t.TempDir()
-			a := newTestAgent(t, cfg, cp, staticProbe(0))
-			a.id = identity{DBInstanceIdentifier: "db-resolved"}
-			a.pending = &pendingBootstrap{payloadID: testPayloadID, vmGeneration: 1}
-			writeReceipt(t, a, tc.payloadID, tc.dbID)
-
-			ctx, cancel := context.WithTimeout(t.Context(), 50*time.Millisecond)
-			defer cancel()
-			if err := a.acknowledgeBootstrap(ctx); err == nil {
-				t.Fatal("acknowledgeBootstrap returned nil, want it still waiting on a real receipt")
-			}
-			if n := len(cp.ackRequests()); n != 0 {
-				t.Errorf("acknowledgements = %d, want 0", n)
-			}
-		})
-	}
-}
-
-// An attach boot has nothing staged, so it must not go looking for a receipt the
-// datadir will never grow.
-func TestAcknowledgeBootstrap_IsANoOpOnAttach(t *testing.T) {
-	cp := newFakeControlPlane()
-	cfg := testConfig(t)
-	cfg.DataMount = t.TempDir()
-	a := newTestAgent(t, cfg, cp, staticProbe(0))
-
-	if err := a.acknowledgeBootstrap(t.Context()); err != nil {
-		t.Fatalf("acknowledgeBootstrap: %v", err)
-	}
-	if n := len(cp.ackRequests()); n != 0 {
-		t.Errorf("acknowledgements = %d, want 0 when nothing was staged", n)
-	}
-}
-
-// The image is the authority on which engine the agent runs. A VM launched as
-// another engine has to stop ahead of the handoff: rds-init would otherwise
-// initialise one engine over the other's datadir and come up healthy and empty
-// beside data nothing references.
-func TestRun_RefusesAnEngineTheImageDoesNotBake(t *testing.T) {
-	cp := newFakeControlPlane()
-	cp.bootstrapOut = bootstrapOutput(nil)
-
-	cfg := testConfig(t)
-	cfg.Engine = "mariadb"
-	a := newTestAgent(t, cfg, cp, staticProbe(0))
-
-	err := a.Run(t.Context())
-	if err == nil {
-		t.Fatal("Run returned nil for a VM launched as an engine this image does not bake")
-	}
-	if !strings.Contains(err.Error(), "mariadb") {
-		t.Errorf("error = %v, want it to name the engine the VM was launched as", err)
-	}
-	if _, statErr := os.Stat(filepath.Join(cfg.HandoffDir, handoffEnvFile)); !os.IsNotExist(statErr) {
-		t.Error("the agent wrote a bootstrap handoff for an engine it refused to run")
-	}
-	if n := len(cp.bootstrapReqs); n != 0 {
-		t.Errorf("bootstrap fetches = %d, want none before the refusal", n)
-	}
-	// Reported rather than only logged, so the control plane learns why the
-	// instance never came up rather than only that it never did.
-	states := cp.snapshotStates()
-	if len(states) != 1 || states[0].health != handlers_rds.EngineHealthUnhealthy {
-		t.Fatalf("submitted states = %+v, want a single unhealthy report", states)
-	}
-}
-
-// The same assertion when it agrees is not a gate: the boot goes on exactly as
-// it does for a VM launched before the control plane sent one at all.
-func TestRun_ProceedsWhenTheDeliveredEngineMatchesTheImage(t *testing.T) {
-	cp := newFakeControlPlane()
-	cp.bootstrapOut = bootstrapOutput(nil)
-
-	cfg := testConfig(t)
-	cfg.Engine = enginePostgres
-	if err := runAgent(t, newTestAgent(t, cfg, cp, staticProbe(0))); err != nil {
-		t.Fatalf("Run: %v", err)
-	}
-}
-
-// A configured identifier is asserted on the wire so a mis-provisioned VM is
-// rejected by the gateway instead of adopting whatever it resolves to.
-func TestRun_SendsConfiguredIdentifier(t *testing.T) {
-	cp := newFakeControlPlane()
-	cp.bootstrapOut = bootstrapOutput(nil)
-
-	cfg := testConfig(t)
-	cfg.DBInstanceIdentifier = "db-configured"
-	cfg.EngineVersion = "18.1"
-	if err := runAgent(t, newTestAgent(t, cfg, cp, staticProbe(0))); err != nil {
-		t.Fatalf("Run: %v", err)
-	}
-
-	sent := cp.registerReqs[0]
-	if sent.DBInstanceIdentifier != "db-configured" || sent.EngineVersion != "18.1" {
-		t.Errorf("register sent %+v, want the configured identifier and engine version", sent)
-	}
-}
-
-func TestRun_WaitsForDataMountBeforePollingCommands(t *testing.T) {
-	cp := newFakeControlPlane()
-	cp.bootstrapOut = bootstrapOutput(nil)
-	cfg := testConfig(t)
-	a := newTestAgent(t, cfg, cp, staticProbe(2))
-
-	waiting := make(chan struct{})
-	release := make(chan struct{})
-	a.dataMountWaiter = func(ctx context.Context, mountsFile, target string) error {
-		if mountsFile != defaultMountsFile || target != cfg.DataMount {
-			t.Errorf("mount waiter got %q/%q, want configured defaults", mountsFile, target)
-		}
-		close(waiting)
-		select {
-		case <-ctx.Done():
-			return ctx.Err()
-		case <-release:
-			return nil
-		}
-	}
-
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-	defer cancel()
-	done := make(chan error, 1)
-	go func() { done <- a.Run(ctx) }()
-
-	select {
-	case <-waiting:
-	case <-ctx.Done():
-		t.Fatal("agent did not reach the data-mount wait after writing the handoff")
-	}
-	if _, err := os.Stat(filepath.Join(cfg.HandoffDir, handoffEnvFile)); err != nil {
-		t.Fatalf("handoff was not present before mount wait: %v", err)
-	}
-	select {
-	case <-cp.polled:
-		t.Fatal("command poll started before the data volume was mounted")
-	case <-time.After(50 * time.Millisecond):
-	}
-
-	close(release)
-	select {
-	case <-cp.polled:
-	case <-ctx.Done():
-		t.Fatal("command poll did not start after the data mount became ready")
-	}
-	cancel()
-	if err := <-done; err != nil {
-		t.Fatalf("Run: %v", err)
-	}
-}
-
-func TestMountTableContains(t *testing.T) {
-	mounts := filepath.Join(t.TempDir(), "mounts")
-	require.NoError(t, os.WriteFile(mounts, []byte(
-		"/dev/vda1 / ext4 rw 0 0\n/dev/vdb /var/lib/postgresql ext4 rw 0 0\n"+
-			"/dev/vdc /path\\040with\\040spaces xfs rw 0 0\nmalformed\n"), 0o600))
-
-	tests := []struct {
-		target string
-		want   bool
-	}{
-		{target: "/var/lib/postgresql", want: true},
-		{target: "/path with spaces", want: true},
-		{target: "/missing", want: false},
-	}
-	for _, tc := range tests {
-		t.Run(tc.target, func(t *testing.T) {
-			got, err := mountTableContains(mounts, tc.target)
-			require.NoError(t, err)
-			assert.Equal(t, tc.want, got)
-		})
-	}
-}
-
-func TestRun_HeartbeatIncludesBootstrapFailure(t *testing.T) {
-	cp := newFakeControlPlane()
-	cp.bootstrapErrs = []error{errors.New("403 AccessDenied: instance profile is not authorised")}
-	cp.registerOut.HeartbeatIntervalSeconds = 0
-
-	cfg := testConfig(t)
-	a := newTestAgent(t, cfg, cp, staticProbe(2))
-	a.hb.interval = 10 * time.Millisecond
-
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-	defer cancel()
-	done := make(chan error, 1)
-	go func() { done <- a.Run(ctx) }()
-
-	waitFor(t, func() bool {
-		for _, state := range cp.snapshotStates() {
-			if strings.Contains(state.message, "bootstrap fetch failed") &&
-				strings.Contains(state.message, "403 AccessDenied") {
-				return true
-			}
-		}
-		return false
-	}, "the bootstrap failure to reach a heartbeat")
-	cancel()
-	<-done
-}
-
-func TestRun_HeartbeatsEngineHealth(t *testing.T) {
-	cp := newFakeControlPlane()
-	cp.bootstrapOut = bootstrapOutput(nil)
-	// Declining to set a cadence leaves the agent's own, which the test shortens
-	// rather than waiting out the 30s production interval.
-	cp.registerOut.HeartbeatIntervalSeconds = 0
-
-	cfg := testConfig(t)
-	a := newTestAgent(t, cfg, cp, staticProbe(0))
-	a.hb.interval = 10 * time.Millisecond
-
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-	defer cancel()
-	done := make(chan error, 1)
-	go func() { done <- a.Run(ctx) }()
-
-	waitFor(t, func() bool { return len(cp.snapshotStates()) > 0 }, "a heartbeat")
-	cancel()
-	<-done
-
-	beat := cp.snapshotStates()[0]
-	if beat.health != handlers_rds.EngineHealthHealthy {
-		t.Errorf("heartbeat health = %q, want healthy", beat.health)
-	}
-	if beat.id.DBInstanceIdentifier != "db-resolved" {
-		t.Errorf("heartbeat identifier = %q, want db-resolved", beat.id.DBInstanceIdentifier)
-	}
-}
-
-// The cadence is the control plane's to set: it feeds the staleness window the
-// recovery reconciler judges an instance against, so the guest adopts it rather
-// than keeping its own.
-func TestRegister_AdoptsControlPlaneCadence(t *testing.T) {
-	cp := newFakeControlPlane()
-	cp.bootstrapOut = bootstrapOutput(nil)
-	cp.registerOut.HeartbeatIntervalSeconds = 45
-
-	cfg := testConfig(t)
-	a := newTestAgent(t, cfg, cp, staticProbe(0))
-	if err := runAgent(t, a); err != nil {
-		t.Fatalf("Run: %v", err)
-	}
-	if a.hb.interval != 45*time.Second {
-		t.Errorf("heartbeat interval = %v, want the 45s the control plane returned", a.hb.interval)
-	}
-}
-
-// The agent being up says nothing about the engine. A down engine has to reach
-// the control plane as such, or auto-recovery has nothing to act on.
-func TestRun_HeartbeatReportsDownEngine(t *testing.T) {
-	cp := newFakeControlPlane()
-	cp.bootstrapOut = bootstrapOutput(nil)
-	cp.registerOut.HeartbeatIntervalSeconds = 0
-
-	cfg := testConfig(t)
-	probe := newPostgresProbe(cfg, staticProbe(2))
-	// The engine has served before, so a silent one now is a failure rather
-	// than a boot still in progress.
-	probe.seenHealthy = true
-
-	a, err := newAgent(cfg, cp, probe)
-	if err != nil {
-		t.Fatalf("newAgent: %v", err)
-	}
-	a.hb.interval = 10 * time.Millisecond
-
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-	defer cancel()
-	done := make(chan error, 1)
-	go func() { done <- a.Run(ctx) }()
-
-	waitFor(t, func() bool { return len(cp.snapshotStates()) > 0 }, "a heartbeat")
-	cancel()
-	<-done
-
-	beat := cp.snapshotStates()[0]
-	if beat.health != handlers_rds.EngineHealthUnhealthy {
-		t.Errorf("heartbeat health = %q, want unhealthy while the agent is up", beat.health)
-	}
-	if beat.message == "" {
-		t.Error("unhealthy heartbeat carried no message explaining the probe result")
-	}
-}
-
-// The mirror the agent decodes poll responses into has to stay aligned with the
-// gateway type that produces them; nothing else in the build ties the two.
-func TestPollDBCommandsOutput_MatchesGatewayShape(t *testing.T) {
-	issued := time.Date(2026, 7, 28, 1, 2, 3, 0, time.UTC)
-	// Rendered exactly as the gateway's typed adapter renders it, so a change to
-	// either side's tags fails here.
-	payload := utils.GenerateIAMXMLPayload("PollDBCommands", &gateway_rds.PollDBCommandsOutput{
-		Commands: []handlers_rds.Command{{
-			CommandID:  "cmd-1",
-			Type:       "reload-parameters",
-			Parameters: []handlers_rds.Parameter{{Name: "work_mem", Value: "8MB"}},
-			IssuedAt:   &issued,
-		}},
-	})
-	body, err := utils.MarshalToXML(payload)
-	if err != nil {
-		t.Fatalf("marshal poll result: %v", err)
-	}
-
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		w.Header().Set("Content-Type", "text/xml")
-		_, _ = w.Write(body)
-	}))
-	defer srv.Close()
-
-	client, err := rdsgw.New(srv.URL, "", gwsign.NewStatic("AKIATEST", "secret"), "us-east-1", time.Second)
-	if err != nil {
-		t.Fatalf("rdsgw.New: %v", err)
-	}
-
-	var got pollDBCommandsOutput
-	if err := client.Call(context.Background(), "PollDBCommands", nil, &got); err != nil {
-		t.Fatalf("Call: %v", err)
-	}
-	if len(got.Commands) != 1 {
-		t.Fatalf("decoded %d commands, want 1", len(got.Commands))
-	}
-	cmd := got.Commands[0]
-	if cmd.CommandID != "cmd-1" || cmd.Type != "reload-parameters" {
-		t.Errorf("command = %+v, want cmd-1/reload-parameters", cmd)
-	}
-	if len(cmd.Parameters) != 1 || cmd.Parameters[0].Value != "8MB" {
-		t.Errorf("Parameters = %+v, want the seeded member", cmd.Parameters)
-	}
-	if cmd.IssuedAt == nil || !cmd.IssuedAt.Equal(issued) {
-		t.Errorf("IssuedAt = %v, want %v", cmd.IssuedAt, issued)
-	}
-}
-
-func readFile(t *testing.T, path string) string {
-	t.Helper()
-	body, err := os.ReadFile(path)
-	if err != nil {
-		t.Fatalf("read %s: %v", path, err)
-	}
-	return string(body)
-}
-
-// AccessDenied is decided by the control plane's own record, so no retry can
-// change it. Looping on one would leave the command poller and the parameter
-// guard unstarted for the life of a VM whose engine is serving normally.
-func TestAcknowledgeBootstrap_StopsOnATerminalDenial(t *testing.T) {
-	cp := newFakeControlPlane()
-	cp.ackErrs = []error{&rdsgw.APIError{
-		Action: "AcknowledgeDBBootstrap", StatusCode: 403,
-		Code:    awserrors.ErrorAccessDenied,
-		Message: "bootstrap payload bp-x at generation 1 does not match the current state",
-	}}
-	cfg := testConfig(t)
-	cfg.DataMount = t.TempDir()
-	a := newTestAgent(t, cfg, cp, staticProbe(0))
-	a.id = identity{DBInstanceIdentifier: "db-resolved"}
-	a.pending = &pendingBootstrap{payloadID: testPayloadID, vmGeneration: 1}
-	writeReceipt(t, a, testPayloadID, "db-resolved")
-
-	ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
-	defer cancel()
-	if err := a.acknowledgeBootstrap(ctx); err != nil {
-		t.Fatalf("acknowledgeBootstrap = %v, want nil so the stateful loops still start", err)
-	}
-	if n := len(cp.ackRequests()); n != 1 {
-		t.Errorf("acknowledgements = %d, want 1 attempt and no retry", n)
-	}
-	if a.hb.bootstrapFailure.Load() == nil {
-		t.Error("a terminal denial must still reach the operator through the heartbeat")
-	}
-	if _, err := os.Stat(a.receiptPath()); err != nil {
-		t.Error("a denied acknowledgement must leave the receipt for a later attempt")
-	}
-}
-
-// rds-init runs after this agent, so the receipt is absent for the whole initdb
-// window. Reporting that would put a failure on every healthy create's beat, and
-// then into the reason a create that timed out for some other cause records.
-func TestAcknowledgeBootstrap_DoesNotReportAnAbsentReceiptAsAFailure(t *testing.T) {
-	cp := newFakeControlPlane()
-	cfg := testConfig(t)
-	cfg.DataMount = t.TempDir()
-	a := newTestAgent(t, cfg, cp, staticProbe(0))
-	a.id = identity{DBInstanceIdentifier: "db-resolved"}
-	a.pending = &pendingBootstrap{payloadID: testPayloadID, vmGeneration: 1}
-
-	ctx, cancel := context.WithTimeout(t.Context(), 50*time.Millisecond)
-	defer cancel()
-	if err := a.acknowledgeBootstrap(ctx); err == nil {
-		t.Fatal("acknowledgeBootstrap returned nil, want it still waiting for rds-init")
-	}
-	if got := a.hb.bootstrapFailure.Load(); got != nil {
-		t.Errorf("bootstrap failure = %q, want none while the receipt has simply not been written", *got)
-	}
-
-	// A receipt that exists but names another instance is a real mismatch and is
-	// reported, which is what separates the two cases.
-	writeReceipt(t, a, testPayloadID, "db-the-snapshot-source")
-	mismatch, cancelMismatch := context.WithTimeout(t.Context(), 50*time.Millisecond)
-	defer cancelMismatch()
-	if err := a.acknowledgeBootstrap(mismatch); err == nil {
-		t.Fatal("a foreign receipt must not be acknowledged")
-	}
-	if a.hb.bootstrapFailure.Load() == nil {
-		t.Error("a receipt naming another instance must be reported")
-	}
-}

cmd/rds-agent/bootstrap.go

@@ -1,237 +0,0 @@
-package main
-
-import (
-	"context"
-	"fmt"
-	"log/slog"
-	"os"
-	"path/filepath"
-	"strconv"
-	"strings"
-
-	handlers_rds "github.com/mulgadc/spinifex/spinifex/handlers/rds"
-)
-
-// The staged payload this boot has to acknowledge once PostgreSQL has applied
-// it. Nil on an attach boot, which makes the acknowledgement step a no-op.
-type pendingBootstrap struct {
-	payloadID    string
-	vmGeneration int64
-	dataVolumeID string
-}
-
-// Fetches the boot material and writes the handoff rds-init is blocked waiting
-// for, then points the health probe at the assigned port.
-func (a *Agent) bootstrap(ctx context.Context) error {
-	var cfg *handlers_rds.GetDBBootstrapConfigOutput
-	if err := retryObserved(ctx, "bootstrap fetch", func(ctx context.Context) error {
-		fetched, err := a.cp.GetBootstrapConfig(ctx, a.id)
-		if err != nil {
-			return err
-		}
-		if fetched == nil {
-			return fmt.Errorf("bootstrap fetch returned no config")
-		}
-		// A control plane predating the encrypted payload answers initialize with
-		// nothing to initialise with. Retrying re-dials the queue group until an
-		// upgraded node answers, so a mixed-version fleet heals within one boot.
-		if fetched.Mode == handlers_rds.BootstrapModeInitialize &&
-			(fetched.MasterUserPassword == nil || *fetched.MasterUserPassword == "") {
-			return fmt.Errorf("bootstrap fetch returned mode=%s with no master password", fetched.Mode)
-		}
-		cfg = fetched
-		return nil
-	}, func(err error) {
-		a.hb.setBootstrapFailure("bootstrap fetch", err)
-	}); err != nil {
-		return err
-	}
-	a.hb.clearBootstrapFailure()
-
-	// The fetch mutates nothing, so a handoff that cannot be written is retried
-	// against the same staged payload rather than against an attach response.
-	if err := retryObserved(ctx, "bootstrap handoff", func(context.Context) error {
-		return a.handoffWriter(a.cfg.HandoffDir, cfg)
-	}, func(err error) {
-		a.hb.setBootstrapFailure("bootstrap handoff", err)
-	}); err != nil {
-		return err
-	}
-	a.hb.clearBootstrapFailure()
-	if cfg.Port > 0 {
-		a.probe.setPort(int(cfg.Port))
-	}
-	if cfg.BootstrapPending && cfg.PayloadID != "" {
-		a.pending = &pendingBootstrap{
-			payloadID:    cfg.PayloadID,
-			vmGeneration: cfg.VMGeneration,
-			dataVolumeID: cfg.DataVolumeID,
-		}
-	}
-	// Mode is logged but never branched on: rds-init decides whether to initdb
-	// from the state of the datadir.
-	slog.Info("rds-agent: bootstrap config delivered",
-		"mode", cfg.Mode, "port", cfg.Port, "parameters", len(cfg.Parameters),
-		"bootstrapPending", cfg.BootstrapPending)
-	return nil
-}
-
-// The handoff files rds-init reads. They live on tmpfs, so nothing survives a
-// reboot and the next boot re-fetches rather than reusing a stale password or a
-// re-minted cert.
-const (
-	handoffEnvFile    = "bootstrap.env"
-	handoffParamsFile = "parameters.conf"
-	handoffCertFile   = "server.crt"
-	handoffKeyFile    = "server.key"
-
-	// Root-only: only rds-init reads these, and one holds the master password.
-	handoffMode    = 0o600
-	handoffDirMode = 0o700
-)
-
-// bootstrap.env is written last and renamed into place, so its appearance —
-// which rds-init waits on — means the whole handoff is complete.
-func writeHandoff(dir string, cfg *handlers_rds.GetDBBootstrapConfigOutput) error {
-	if cfg.MasterUsername == "" {
-		return fmt.Errorf("bootstrap config carries no master username")
-	}
-	// Half a handoff would leave rds-init deciding what to bind and who to admit,
-	// and the only answers it could reach on its own are the wildcards this
-	// contract exists to remove.
-	if cfg.ListenAddress == "" {
-		return fmt.Errorf("bootstrap config carries no listen address for the engine to bind")
-	}
-	if cfg.ClientCIDR == "" {
-		return fmt.Errorf("bootstrap config carries no client CIDR to scope client authentication to")
-	}
-	if err := os.MkdirAll(dir, handoffDirMode); err != nil {
-		return fmt.Errorf("create handoff dir %s: %w", dir, err)
-	}
-	// MkdirAll leaves an existing directory's mode alone, and this one may have
-	// been created more permissively earlier in the boot.
-	if err := os.Chmod(dir, handoffDirMode); err != nil {
-		return fmt.Errorf("secure handoff dir %s: %w", dir, err)
-	}
-
-	params, err := renderParameters(cfg.Engine, cfg.Parameters)
-	if err != nil {
-		return err
-	}
-	if err := writeHandoffFile(dir, handoffParamsFile, params); err != nil {
-		return err
-	}
-	// Cert and key are written as a pair; half of one would start the engine
-	// with TLS configured against a key it does not have.
-	if cfg.ServingCertificate != "" && cfg.ServingPrivateKey != "" {
-		if err := writeHandoffFile(dir, handoffCertFile, cfg.ServingCertificate); err != nil {
-			return err
-		}
-		if err := writeHandoffFile(dir, handoffKeyFile, cfg.ServingPrivateKey); err != nil {
-			return err
-		}
-	}
-
-	return writeHandoffFile(dir, handoffEnvFile, renderBootstrapEnv(cfg))
-}
-
-// Every value is single-quoted because rds-init sources this with `.`: an
-// unquoted password holding a space, `$` or `;` would be word-split or executed.
-func renderBootstrapEnv(cfg *handlers_rds.GetDBBootstrapConfigOutput) string {
-	var b strings.Builder
-	b.WriteString("# Written by rds-agent. Regenerated on every boot; edits are lost.\n")
-	writeEnvLine(&b, "RDS_MODE", cfg.Mode)
-	writeEnvLine(&b, "RDS_DB_INSTANCE_IDENTIFIER", cfg.DBInstanceIdentifier)
-	writeEnvLine(&b, "RDS_MASTER_USERNAME", cfg.MasterUsername)
-	writeEnvLine(&b, "RDS_LISTEN_ADDRESS", cfg.ListenAddress)
-	writeEnvLine(&b, "RDS_CLIENT_CIDR", cfg.ClientCIDR)
-	writeEnvLine(&b, "RDS_DATA_VOLUME_ID", cfg.DataVolumeID)
-	writeEnvLine(&b, "RDS_DATA_VOLUME_SERIAL", cfg.DataVolumeSerial)
-	writeEnvLine(&b, "RDS_VM_GENERATION", strconv.FormatInt(cfg.VMGeneration, 10))
-	writeEnvLine(&b, "RDS_FORMAT_AUTHORIZED", strconv.FormatBool(cfg.FormatAuthorized))
-	// Neither needs volume access, which is why the assertion is made here: the
-	// agent runs before rds-datadir mounts the volume, so rds-init is the first
-	// component that can compare it against the completion receipt on disk.
-	writeEnvLine(&b, "RDS_BOOTSTRAP_PENDING", boolFlag(cfg.BootstrapPending))
-	writeEnvLine(&b, "RDS_PAYLOAD_ID", cfg.PayloadID)
-	// Present only in initialize mode: an attach fetch has no password to write
-	// and rds-init must not find a stale one.
-	if cfg.MasterUserPassword != nil {
-		writeEnvLine(&b, "RDS_MASTER_PASSWORD", *cfg.MasterUserPassword)
-	}
-	if cfg.DBName != "" {
-		writeEnvLine(&b, "RDS_DB_NAME", cfg.DBName)
-	}
-	if cfg.Port > 0 {
-		writeEnvLine(&b, "RDS_PORT", strconv.FormatInt(cfg.Port, 10))
-	}
-	return b.String()
-}
-
-// rds-init compares against 1 rather than sourcing a Go boolean, so the two
-// halves of the guard cannot drift on spelling.
-func boolFlag(v bool) string {
-	if v {
-		return "1"
-	}
-	return "0"
-}
-
-func writeEnvLine(b *strings.Builder, key, value string) {
-	b.WriteString(key)
-	b.WriteString("=")
-	b.WriteString(shellQuote(value))
-	b.WriteString("\n")
-}
-
-// Single quotes suppress every shell expansion; an embedded quote is closed,
-// escaped and reopened.
-func shellQuote(s string) string {
-	return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'"
-}
-
-// postgresql.conf syntax, which MariaDB's option files also parse. Values are
-// quoted so a space or unit suffix survives. Names are the engine's startup
-// spellings, not the customer's: the wrong one leaves the engine unable to boot.
-func renderParameters(engineName string, params []handlers_rds.Parameter) (string, error) {
-	engine, err := handlers_rds.LookupEngine(engineName)
-	if err != nil {
-		return "", fmt.Errorf("render the resolved parameters: %w", err)
-	}
-	var b strings.Builder
-	b.WriteString("# Resolved parameter group, written by rds-agent.\n")
-	for _, p := range params {
-		if p.Name == "" {
-			continue
-		}
-		fmt.Fprintf(&b, "%s = '%s'\n", engine.OptionFileName(p.Name), strings.ReplaceAll(p.Value, "'", "''"))
-	}
-	return b.String(), nil
-}
-
-// Atomic: a temp file in the same directory, renamed over the target. The mode
-// is set at creation, so content is never briefly readable at the process umask.
-func writeHandoffFile(dir, name, content string) error {
-	path := filepath.Join(dir, name)
-	tmp := path + ".new"
-
-	f, err := os.OpenFile(tmp, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, handoffMode)
-	if err != nil {
-		return fmt.Errorf("create %s: %w", tmp, err)
-	}
-	// A failed write must not leave the temp file behind holding a password.
-	if _, err := f.WriteString(content); err != nil {
-		f.Close()
-		os.Remove(tmp)
-		return fmt.Errorf("write %s: %w", tmp, err)
-	}
-	if err := f.Close(); err != nil {
-		os.Remove(tmp)
-		return fmt.Errorf("close %s: %w", tmp, err)
-	}
-	if err := os.Rename(tmp, path); err != nil {
-		os.Remove(tmp)
-		return fmt.Errorf("install %s: %w", path, err)
-	}
-	return nil
-}

cmd/rds-agent/bootstrap_test.go

@@ -1,280 +0,0 @@
-package main
-
-import (
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	handlers_rds "github.com/mulgadc/spinifex/spinifex/handlers/rds"
-)
-
-func TestWriteHandoff_WritesEveryFileRootOnly(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "handoff")
-	password := "s3cret"
-
-	err := writeHandoff(dir, &handlers_rds.GetDBBootstrapConfigOutput{
-		Mode:               handlers_rds.BootstrapModeInitialize,
-		Engine:             "postgres",
-		MasterUsername:     "master",
-		ListenAddress:      "10.0.1.20",
-		ClientCIDR:         "10.0.0.0/16",
-		MasterUserPassword: &password,
-		DBName:             "appdb",
-		Port:               5433,
-		DataVolumeID:       "vol-data-01",
-		DataVolumeSerial:   "voldata01",
-		VMGeneration:       4,
-		FormatAuthorized:   true,
-		Parameters: []handlers_rds.Parameter{
-			{Name: "max_connections", Value: "200"},
-			{Name: "shared_buffers", Value: "256MB"},
-		},
-		ServingCertificate: "CERT",
-		ServingPrivateKey:  "KEY",
-	})
-	if err != nil {
-		t.Fatalf("writeHandoff: %v", err)
-	}
-
-	env := readFile(t, filepath.Join(dir, handoffEnvFile))
-	for _, want := range []string{
-		"RDS_MODE='initialize'",
-		"RDS_MASTER_USERNAME='master'",
-		"RDS_MASTER_PASSWORD='s3cret'",
-		"RDS_DB_NAME='appdb'",
-		"RDS_PORT='5433'",
-		"RDS_DATA_VOLUME_ID='vol-data-01'",
-		"RDS_DATA_VOLUME_SERIAL='voldata01'",
-		"RDS_VM_GENERATION='4'",
-		"RDS_FORMAT_AUTHORIZED='true'",
-	} {
-		if !strings.Contains(env, want) {
-			t.Errorf("handoff env missing %s:\n%s", want, env)
-		}
-	}
-
-	params := readFile(t, filepath.Join(dir, handoffParamsFile))
-	if !strings.Contains(params, "max_connections = '200'") || !strings.Contains(params, "shared_buffers = '256MB'") {
-		t.Errorf("parameters.conf = %q, want both resolved settings", params)
-	}
-	if got := readFile(t, filepath.Join(dir, handoffCertFile)); got != "CERT" {
-		t.Errorf("server.crt = %q, want CERT", got)
-	}
-	if got := readFile(t, filepath.Join(dir, handoffKeyFile)); got != "KEY" {
-		t.Errorf("server.key = %q, want KEY", got)
-	}
-
-	// The handoff holds a master password and a private key; anything readable
-	// beyond root is a disclosure to every process in the guest.
-	if mode := statMode(t, dir); mode != handoffDirMode {
-		t.Errorf("handoff dir mode = %#o, want %#o", mode, handoffDirMode)
-	}
-	for _, name := range []string{handoffEnvFile, handoffParamsFile, handoffCertFile, handoffKeyFile} {
-		if mode := statMode(t, filepath.Join(dir, name)); mode != handoffMode {
-			t.Errorf("%s mode = %#o, want %#o", name, mode, handoffMode)
-		}
-	}
-}
-
-// Attach mode carries no password, and the key must be absent rather than
-// present and empty — rds-init reads an empty value as "no password" only by
-// accident, and a later boot would inherit it.
-func TestWriteHandoff_AttachOmitsPassword(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "handoff")
-	if err := writeHandoff(dir, &handlers_rds.GetDBBootstrapConfigOutput{
-		Mode:           handlers_rds.BootstrapModeAttach,
-		Engine:         "postgres",
-		MasterUsername: "master",
-		ListenAddress:  "10.0.1.20",
-		ClientCIDR:     "10.0.0.0/16",
-		Port:           5432,
-	}); err != nil {
-		t.Fatalf("writeHandoff: %v", err)
-	}
-
-	env := readFile(t, filepath.Join(dir, handoffEnvFile))
-	if strings.Contains(env, "RDS_MASTER_PASSWORD") {
-		t.Errorf("handoff env = %q, want no RDS_MASTER_PASSWORD key", env)
-	}
-	for _, want := range []string{
-		"RDS_DATA_VOLUME_ID=''",
-		"RDS_DATA_VOLUME_SERIAL=''",
-		"RDS_VM_GENERATION='0'",
-		"RDS_FORMAT_AUTHORIZED='false'",
-	} {
-		if !strings.Contains(env, want) {
-			t.Errorf("handoff env missing fail-closed field %s: %q", want, env)
-		}
-	}
-}
-
-// The env file is sourced by a shell, so a password holding shell metacharacters
-// must survive as data rather than being split, expanded or executed.
-func TestWriteHandoff_QuotesShellMetacharacters(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "handoff")
-	password := `a b$(id);'"\` + "`whoami`"
-
-	if err := writeHandoff(dir, &handlers_rds.GetDBBootstrapConfigOutput{
-		Mode:               handlers_rds.BootstrapModeInitialize,
-		Engine:             "postgres",
-		MasterUsername:     "master",
-		ListenAddress:      "10.0.1.20",
-		ClientCIDR:         "10.0.0.0/16",
-		MasterUserPassword: &password,
-		Port:               5432,
-	}); err != nil {
-		t.Fatalf("writeHandoff: %v", err)
-	}
-
-	env := readFile(t, filepath.Join(dir, handoffEnvFile))
-	line := findLine(t, env, "RDS_MASTER_PASSWORD=")
-	if got := shellSource(t, line, "RDS_MASTER_PASSWORD"); got != password {
-		t.Errorf("sourced password = %q, want %q (line was %s)", got, password, line)
-	}
-}
-
-// A serving cert with no key would have rds-init configure TLS against a key
-// that is not there; the pair is delivered together or not at all.
-func TestWriteHandoff_SkipsHalfATLSPair(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "handoff")
-	if err := writeHandoff(dir, &handlers_rds.GetDBBootstrapConfigOutput{
-		Mode:               handlers_rds.BootstrapModeAttach,
-		Engine:             "postgres",
-		MasterUsername:     "master",
-		ListenAddress:      "10.0.1.20",
-		ClientCIDR:         "10.0.0.0/16",
-		Port:               5432,
-		ServingCertificate: "CERT",
-	}); err != nil {
-		t.Fatalf("writeHandoff: %v", err)
-	}
-
-	if _, err := os.Stat(filepath.Join(dir, handoffCertFile)); !os.IsNotExist(err) {
-		t.Errorf("server.crt exists without a key; stat err = %v", err)
-	}
-}
-
-// A config with no master username cannot bootstrap anything, and writing it
-// would only move the failure into rds-init after the boot has committed to it.
-func TestWriteHandoff_RejectsConfigWithNoMasterUser(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "handoff")
-	err := writeHandoff(dir, &handlers_rds.GetDBBootstrapConfigOutput{
-		Mode:   handlers_rds.BootstrapModeAttach,
-		Engine: "postgres",
-		Port:   5432,
-	})
-	if err == nil {
-		t.Fatal("writeHandoff accepted a config with no master username, want an error")
-	}
-	if _, statErr := os.Stat(filepath.Join(dir, handoffEnvFile)); !os.IsNotExist(statErr) {
-		t.Errorf("handoff env was written despite the rejection; stat err = %v", statErr)
-	}
-}
-
-// A directory left over from an earlier boot at a looser mode must be tightened,
-// not accepted as it is found.
-func TestWriteHandoff_TightensExistingDirectory(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "handoff")
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		t.Fatalf("seed dir: %v", err)
-	}
-
-	if err := writeHandoff(dir, &handlers_rds.GetDBBootstrapConfigOutput{
-		Mode:           handlers_rds.BootstrapModeAttach,
-		Engine:         "postgres",
-		MasterUsername: "master",
-		ListenAddress:  "10.0.1.20",
-		ClientCIDR:     "10.0.0.0/16",
-		Port:           5432,
-	}); err != nil {
-		t.Fatalf("writeHandoff: %v", err)
-	}
-	if mode := statMode(t, dir); mode != handoffDirMode {
-		t.Errorf("handoff dir mode = %#o, want it tightened to %#o", mode, handoffDirMode)
-	}
-}
-
-func TestShellQuote_EscapesEmbeddedQuotes(t *testing.T) {
-	for _, in := range []string{"", "plain", "it's", `''`, "new\nline", `$HOME`} {
-		if got := shellSource(t, "V="+shellQuote(in), "V"); got != in {
-			t.Errorf("shellQuote(%q) sourced back as %q", in, got)
-		}
-	}
-}
-
-// shellSource evaluates one KEY=value assignment in a real shell and returns
-// what the variable ends up holding. The quoting is only correct if a shell
-// agrees, so the test asks one instead of re-implementing its rules.
-func shellSource(t *testing.T, line, name string) string {
-	t.Helper()
-	out, err := exec.Command("/bin/sh", "-c", line+"\nprintf %s \"$"+name+"\"\n").Output()
-	if err != nil {
-		t.Fatalf("sourcing %q: %v", line, err)
-	}
-	return string(out)
-}
-
-func statMode(t *testing.T, path string) os.FileMode {
-	t.Helper()
-	info, err := os.Stat(path)
-	if err != nil {
-		t.Fatalf("stat %s: %v", path, err)
-	}
-	return info.Mode().Perm()
-}
-
-func findLine(t *testing.T, body, prefix string) string {
-	t.Helper()
-	for line := range strings.SplitSeq(body, "\n") {
-		if strings.HasPrefix(line, prefix) {
-			return line
-		}
-	}
-	t.Fatalf("no line starting %q in:\n%s", prefix, body)
-	return ""
-}
-
-// The include rds-init installs is what the engine starts on, so the spelling
-// written here is the one that has to boot.
-func TestRenderParameters_UsesTheEngineStartupSpelling(t *testing.T) {
-	params := []handlers_rds.Parameter{
-		{Name: "time_zone", Value: "SYSTEM"},
-		{Name: "max_connections", Value: "85"},
-	}
-
-	rendered, err := renderParameters("mariadb", params)
-	if err != nil {
-		t.Fatalf("renderParameters: %v", err)
-	}
-	if !strings.Contains(rendered, "default_time_zone = 'SYSTEM'\n") {
-		t.Errorf("time_zone was not written under its startup spelling:\n%s", rendered)
-	}
-	if strings.Contains(rendered, "\ntime_zone = ") {
-		t.Errorf("time_zone reached the option file, which mariadbd refuses:\n%s", rendered)
-	}
-	if !strings.Contains(rendered, "max_connections = '85'\n") {
-		t.Errorf("an unmapped parameter was not written unchanged:\n%s", rendered)
-	}
-}
-
-func TestRenderParameters_PostgresKeepsEveryName(t *testing.T) {
-	rendered, err := renderParameters("postgres", []handlers_rds.Parameter{
-		{Name: "shared_buffers", Value: "262144"},
-	})
-	if err != nil {
-		t.Fatalf("renderParameters: %v", err)
-	}
-	if !strings.Contains(rendered, "shared_buffers = '262144'\n") {
-		t.Errorf("postgres name was rewritten:\n%s", rendered)
-	}
-}
-
-// Failing closed beats writing a file the engine may refuse: the bad include
-// would already be on the data volume by the time the server rejected it.
-func TestRenderParameters_RefusesAnUnknownEngine(t *testing.T) {
-	if _, err := renderParameters("", nil); err == nil {
-		t.Fatal("renderParameters accepted a config naming no engine, want an error")
-	}
-}

cmd/rds-agent/command.go

@@ -1,160 +0,0 @@
-package main
-
-import (
-	"context"
-	"fmt"
-	"log/slog"
-	"strconv"
-	"strings"
-	"time"
-
-	handlers_rds "github.com/mulgadc/spinifex/spinifex/handlers/rds"
-)
-
-// Executes one control-plane directive inside the guest and returns the message
-// reported back to the issuer.
-type commandHandler func(ctx context.Context, cmd handlers_rds.Command) (string, error)
-
-// A registry rather than a dispatch switch, so guest operations — password
-// apply, parameter reload, storage grow, snapshot quiesce — add an entry each.
-type commandRegistry map[string]commandHandler
-
-// An unregistered type is replied to as unsupported, so a control plane ahead
-// of the guest gets a clear answer rather than a timeout.
-func newCommandRegistry(engine engineOps, storage storageOps) commandRegistry {
-	return commandRegistry{
-		handlers_rds.CommandSetPassword: func(ctx context.Context, cmd handlers_rds.Command) (string, error) {
-			params := commandParams(cmd)
-			return "", engine.SetPassword(ctx,
-				params[handlers_rds.CommandParamMasterUsername],
-				params[handlers_rds.CommandParamMasterUserPassword])
-		},
-		handlers_rds.CommandApplyParams: func(ctx context.Context, cmd handlers_rds.Command) (string, error) {
-			pending, err := engine.ApplyParameters(ctx, cmd.Parameters)
-			if err != nil {
-				return "", err
-			}
-			// The reply carries no structured payload, so the settings still
-			// awaiting a restart come back as the message itself.
-			return strings.Join(pending, ","), nil
-		},
-		handlers_rds.CommandStopEngine: func(ctx context.Context, cmd handlers_rds.Command) (string, error) {
-			return "", engine.Stop(ctx)
-		},
-		handlers_rds.CommandGrowFilesystem: func(ctx context.Context, cmd handlers_rds.Command) (string, error) {
-			return storage.GrowFilesystem(ctx)
-		},
-		handlers_rds.CommandQuiesce: func(ctx context.Context, cmd handlers_rds.Command) (string, error) {
-			params := commandParams(cmd)
-			hold, err := quiesceHoldFrom(params[handlers_rds.CommandParamQuiesceDeadlineSeconds])
-			if err != nil {
-				return "", err
-			}
-			return "", engine.Quiesce(ctx, params[handlers_rds.CommandParamQuiesceLabel], hold)
-		},
-		handlers_rds.CommandUnquiesce: func(ctx context.Context, cmd handlers_rds.Command) (string, error) {
-			return "", engine.Unquiesce(ctx)
-		},
-	}
-}
-
-// The control plane's hold deadline. A missing or unreadable one is refused
-// rather than defaulted: a hold the guest chose the length of would not be the
-// bound the control plane is relying on.
-func quiesceHoldFrom(value string) (time.Duration, error) {
-	seconds, err := strconv.Atoi(strings.TrimSpace(value))
-	if err != nil || seconds <= 0 {
-		return 0, fmt.Errorf("%s must be a positive number of seconds, got %q",
-			handlers_rds.CommandParamQuiesceDeadlineSeconds, value)
-	}
-	return time.Duration(seconds) * time.Second, nil
-}
-
-// A later value wins, so a malformed command carrying a parameter twice cannot
-// leave the handler acting on the first of two conflicting values.
-func commandParams(cmd handlers_rds.Command) map[string]string {
-	params := make(map[string]string, len(cmd.Parameters))
-	for _, p := range cmd.Parameters {
-		params[p.Name] = p.Value
-	}
-	return params
-}
-
-// Spaces retries after a failed poll, so a broken channel is not re-polled at
-// line rate for as long as it stays broken.
-const pollErrorBackoff = 5 * time.Second
-
-// The agent's command channel: a long poll that carries back the replies for
-// whatever the previous poll delivered.
-type commander struct {
-	cp       controlPlane
-	id       identity
-	registry commandRegistry
-	wait     time.Duration
-	// Cleared only once a poll has carried them, so a failed poll re-delivers
-	// rather than dropping the result of work the guest actually did.
-	pending []handlers_rds.CommandReply
-}
-
-func newCommander(cp controlPlane, registry commandRegistry, wait time.Duration) *commander {
-	if wait <= 0 {
-		wait = defaultPollWait
-	}
-	return &commander{cp: cp, registry: registry, wait: wait}
-}
-
-func (c *commander) Run(ctx context.Context) {
-	for {
-		if ctx.Err() != nil {
-			return
-		}
-		commands, err := c.cp.PollCommands(ctx, c.id, c.pending, c.wait)
-		if err != nil {
-			if ctx.Err() != nil {
-				return
-			}
-			slog.Warn("rds-agent: command poll failed", "err", err)
-			select {
-			case <-ctx.Done():
-				return
-			case <-time.After(pollErrorBackoff):
-			}
-			continue
-		}
-		c.pending = nil
-
-		for _, cmd := range commands {
-			c.pending = append(c.pending, c.execute(ctx, cmd))
-		}
-	}
-}
-
-// Every command gets a reply: the issuer is blocked on this command ID, so a
-// silent drop costs it a full timeout.
-func (c *commander) execute(ctx context.Context, cmd handlers_rds.Command) handlers_rds.CommandReply {
-	handler, ok := c.registry[cmd.Type]
-	if !ok {
-		slog.Warn("rds-agent: unsupported command", "commandID", cmd.CommandID, "type", cmd.Type)
-		return failedReply(cmd, fmt.Sprintf("unsupported command type %q", cmd.Type))
-	}
-
-	slog.Info("rds-agent: executing command", "commandID", cmd.CommandID, "type", cmd.Type)
-	message, err := handler(ctx, cmd)
-	if err != nil {
-		slog.Error("rds-agent: command failed", "commandID", cmd.CommandID, "type", cmd.Type, "err", err)
-		return failedReply(cmd, err.Error())
-	}
-	return handlers_rds.CommandReply{
-		CommandID: cmd.CommandID,
-		Status:    handlers_rds.CommandStatusSucceeded,
-		Message:   message,
-	}
-}
-
-func failedReply(cmd handlers_rds.Command, message string) handlers_rds.CommandReply {
-	return handlers_rds.CommandReply{
-		CommandID: cmd.CommandID,
-		Status:    handlers_rds.CommandStatusFailed,
-		Message:   message,
-	}
-}