chore: bump the go-dependencies group with 13 updates (#1214 )

Bumps the go-dependencies group with 13 updates: | Package | From | To | | --- | --- | --- | | [github.com/aws/aws-sdk-go-v2](https://github.com/aws/aws-sdk-go-v2) | `1.47.1` | `1.47.3` | | [github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream](https://github.com/aws/aws-sdk-go-v2) | `1.7.20` | `1.7.22` | | [github.com/aws/aws-sdk-go-v2/config](https://github.com/aws/aws-sdk-go-v2) | `1.33.7` | `1.33.9` | | [github.com/aws/aws-sdk-go-v2/credentials](https://github.com/aws/aws-sdk-go-v2) | `1.20.7` | `1.20.9` | | [github.com/aws/aws-sdk-go-v2/feature/ec2/imds](https://github.com/aws/aws-sdk-go-v2) | `1.20.1` | `1.20.3` | | [github.com/containerd/containerd/v2](https://github.com/containerd/containerd) | `2.4.1` | `2.4.2` | | [github.com/go-chi/chi/v5](https://github.com/go-chi/chi) | `5.3.2` | `5.5.0` | | [github.com/klauspost/compress](https://github.com/klauspost/compress) | `1.20.1` | `1.20.3` | | [github.com/klauspost/cpuid/v2](https://github.com/klauspost/cpuid) | `2.4.0` | `2.4.1` | | [github.com/nats-io/nats-server/v2](https://github.com/nats-io/nats-server) | `2.15.0` | `2.15.1` | | [github.com/oracle/oci-go-sdk/v65](https://github.com/oracle/oci-go-sdk) | `65.126.2` | `65.127.0` | | [github.com/pterm/pterm](https://github.com/pterm/pterm) | `0.12.83` | `0.12.84` | | [golang.org/x/tools](https://github.com/golang/tools) | `0.51.0` | `0.52.0` | Updates `github.com/aws/aws-sdk-go-v2` from 1.47.1 to 1.47.3 - [Release notes](https://github.com/aws/aws-sdk-go-v2/releases) - [Commits](https://github.com/aws/aws-sdk-go-v2/compare/v1.47.1...v1.47.3) Updates `github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream` from 1.7.20 to 1.7.22 - [Release notes](https://github.com/aws/aws-sdk-go-v2/releases) - [Commits](https://github.com/aws/aws-sdk-go-v2/compare/service/notifications/v1.7.20...service/notifications/v1.7.22) Updates `github.com/aws/aws-sdk-go-v2/config` from 1.33.7 to 1.33.9 - [Release notes](https://github.com/aws/aws-sdk-go-v2/releases) - [Commits](https://github.com/aws/aws-sdk-go-v2/compare/config/v1.33.7...config/v1.33.9) Updates `github.com/aws/aws-sdk-go-v2/credentials` from 1.20.7 to 1.20.9 - [Release notes](https://github.com/aws/aws-sdk-go-v2/releases) - [Commits](https://github.com/aws/aws-sdk-go-v2/compare/service/mq/v1.20.7...service/kms/v1.20.9) Updates `github.com/aws/aws-sdk-go-v2/feature/ec2/imds` from 1.20.1 to 1.20.3 - [Release notes](https://github.com/aws/aws-sdk-go-v2/releases) - [Commits](https://github.com/aws/aws-sdk-go-v2/compare/v1.20.1...v1.20.3) Updates `github.com/containerd/containerd/v2` from 2.4.1 to 2.4.2 - [Release notes](https://github.com/containerd/containerd/releases) - [Changelog](https://github.com/containerd/containerd/blob/main/RELEASES.md) - [Commits](https://github.com/containerd/containerd/compare/v2.4.1...v2.4.2) Updates `github.com/go-chi/chi/v5` from 5.3.2 to 5.5.0 - [Release notes](https://github.com/go-chi/chi/releases) - [Changelog](https://github.com/go-chi/chi/blob/master/CHANGELOG.md) - [Commits](https://github.com/go-chi/chi/compare/v5.3.2...v5.5.0) Updates `github.com/klauspost/compress` from 1.20.1 to 1.20.3 - [Release notes](https://github.com/klauspost/compress/releases) - [Commits](https://github.com/klauspost/compress/compare/v1.20.1...v1.20.3) Updates `github.com/klauspost/cpuid/v2` from 2.4.0 to 2.4.1 - [Release notes](https://github.com/klauspost/cpuid/releases) - [Commits](https://github.com/klauspost/cpuid/compare/v2.4.0...v2.4.1) Updates `github.com/nats-io/nats-server/v2` from 2.15.0 to 2.15.1 - [Release notes](https://github.com/nats-io/nats-server/releases) - [Changelog](https://github.com/nats-io/nats-server/blob/main/RELEASES.md) - [Commits](https://github.com/nats-io/nats-server/compare/v2.15.0...v2.15.1) Updates `github.com/oracle/oci-go-sdk/v65` from 65.126.2 to 65.127.0 - [Release notes](https://github.com/oracle/oci-go-sdk/releases) - [Changelog](https://github.com/oracle/oci-go-sdk/blob/master/CHANGELOG.md) - [Commits](https://github.com/oracle/oci-go-sdk/compare/v65.126.2...v65.127.0) Updates `github.com/pterm/pterm` from 0.12.83 to 0.12.84 - [Release notes](https://github.com/pterm/pterm/releases) - [Commits](https://github.com/pterm/pterm/compare/v0.12.83...v0.12.84) Updates `golang.org/x/tools` from 0.51.0 to 0.52.0 - [Release notes](https://github.com/golang/tools/releases) - [Commits](https://github.com/golang/tools/compare/v0.51.0...v0.52.0) --- updated-dependencies: - dependency-name: github.com/aws/aws-sdk-go-v2 dependency-version: 1.47.3 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: go-dependencies - dependency-name: github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream dependency-version: 1.7.22 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: go-dependencies - dependency-name: github.com/aws/aws-sdk-go-v2/config dependency-version: 1.33.9 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: go-dependencies - dependency-name: github.com/aws/aws-sdk-go-v2/credentials dependency-version: 1.20.9 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: go-dependencies - dependency-name: github.com/aws/aws-sdk-go-v2/feature/ec2/imds dependency-version: 1.20.3 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: go-dependencies - dependency-name: github.com/containerd/containerd/v2 dependency-version: 2.4.2 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: go-dependencies - dependency-name: github.com/go-chi/chi/v5 dependency-version: 5.5.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: go-dependencies - dependency-name: github.com/klauspost/compress dependency-version: 1.20.3 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: go-dependencies - dependency-name: github.com/klauspost/cpuid/v2 dependency-version: 2.4.1 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: go-dependencies - dependency-name: github.com/nats-io/nats-server/v2 dependency-version: 2.15.1 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: go-dependencies - dependency-name: github.com/oracle/oci-go-sdk/v65 dependency-version: 65.127.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: go-dependencies - dependency-name: github.com/pterm/pterm dependency-version: 0.12.84 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: go-dependencies - dependency-name: golang.org/x/tools dependency-version: 0.52.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: go-dependencies ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
feat: add read-only EC2 platform inventory for account termination (#1212 )
2026-10-23 20:57:02 +00:00 · 2026-10-19 09:01:24 +11:00 · 2026-10-16 12:05:32 +10:00 · 2026-10-16 12:01:14 +10:00 · 2026-10-16 11:25:57 +10:00 · 2026-10-15 16:47:03 +10:00
3523 changed files with 53605 additions and 27264 deletions
@@ -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
@@ -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"
@@ -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"/>
@@ -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">
@@ -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:
+          - "*"
@@ -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.
@@ -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
@@ -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.0.10'
+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.0.10':
+        ref: 'v6.0.10'
+        commit: 'sha1-0977fd99725f1db4007ccb2928dbb4e90d06cc86'
+        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
@@ -40,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 }}
@@ -34,7 +34,7 @@ jobs:
      # 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
+        uses: actions/checkout@v7.0.1
        with:
          path: spinifex
          fetch-depth: 0
@@ -42,40 +42,41 @@ jobs:
      # 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
+        uses: actions/checkout@v7.0.1
        with:
          repository: mulgadc/predastore
          ref: dev
          path: predastore

      - name: Checkout Viperblock
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
        with:
          repository: mulgadc/viperblock
          ref: dev
          path: viperblock

      - name: Checkout Northstar
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
        with:
          repository: mulgadc/northstar
          ref: dev
          path: northstar

      - name: Checkout Bluebottle
-        uses: actions/checkout@v7
+        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
+        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-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
@@ -167,11 +168,7 @@ jobs:

      # 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, and each build carries two assets.
-      #
-      # Twenty, not five. A pinned dev tag is how an external evaluator installs a
-      # specific build, and five is about a week of them -- short enough that the tag
-      # someone was given stops resolving while they are still using it.
+      # 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:
@@ -179,7 +176,7 @@ jobs:
        run: |
          set -euo pipefail
          gh api "repos/$GITHUB_REPOSITORY/releases?per_page=100" \
-              --jq 'map(select(.prerelease and (.tag_name | endswith("-dev")))) | .[20:] | .[].tag_name' \
+              --jq 'map(select(.prerelease and (.tag_name | endswith("-dev")))) | .[5:] | .[].tag_name' \
              > stale.txt
          while read -r tag; do
              [ -n "$tag" ] || continue
@@ -77,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 }}
@@ -151,7 +151,8 @@ 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
@@ -221,20 +222,20 @@ 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: ${{ 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 ${{ env.BM_CELL }})"

-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@v7.0.2
        if: always()
        with:
          name: e2e-artifacts-cell-${{ env.BM_CELL }}-${{ github.run_id }}
@@ -76,11 +76,11 @@ jobs:
      - name: Put the Terraform state outside the checkout
        run: echo "OCI_STATE_ROOT=$RUNNER_WORKSPACE/oci-state" >> "$GITHUB_ENV"

-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          path: spinifex

-      - 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 }}
@@ -92,14 +92,14 @@ jobs:

      # 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
+      - 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
+      - uses: hashicorp/setup-terraform@v4.0.1
        with:
          terraform_wrapper: false

@@ -273,7 +273,7 @@ jobs:
      # collect step above chose, so terraform.tfstate cannot reach an artifact.
      - name: Upload the run
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
        with:
          name: e2e-oci-${{ github.run_id }}
          path: |
@@ -38,19 +38,19 @@ jobs:
      - 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

@@ -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
@@ -234,7 +234,7 @@ jobs:

      - 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 }}
@@ -43,7 +43,7 @@ jobs:
      cells: ${{ steps.pick.outputs.cells }}
      any: ${{ steps.pick.outputs.any }}
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          sparse-checkout: |
            .github/e2e-cells.json
@@ -128,21 +128,21 @@ 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/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

@@ -151,7 +151,7 @@ jobs:
      # links each cell's telemetry to the job log that produced it. Runs
      # before Bootstrap bakes SPINIFEX_OTEL_ATTRS into the VM's telemetry.env.
      - name: Resolve CI job id
-        uses: ./spinifex/.github/actions/otel-job-id
+        uses: $/.github/actions/otel-job-id
        with:
          job-name: "cell-${{ matrix.cell }} (${{ matrix.topo }}/${{ matrix.net }}/${{ matrix.host }}${{ matrix.extra && format('/{0}', matrix.extra) || '' }})"

@@ -795,7 +795,8 @@ jobs:
      - name: Install go-junit-report
        if: always()
        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: Convert test logs to JUnit XML
@@ -812,20 +813,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: ${{ matrix.cell }}

      - 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 (cell ${{ matrix.cell }})"

-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@v7.0.2
        if: always()
        with:
          name: e2e-artifacts-cell-${{ matrix.cell }}-${{ github.run_id }}
@@ -837,7 +838,7 @@ jobs:
      # pulling nineteen journals it has no use for.
      - name: Upload junit only
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
        with:
          name: junit-cell-${{ matrix.cell }}-${{ github.run_id }}
          path: ${{ env.ARTIFACT_DIR }}/junit-*.xml
@@ -868,7 +869,7 @@ jobs:

      - name: Upload tofu log
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
        with:
          name: tofu-log-cell-${{ matrix.cell }}-${{ github.run_id }}
          path: ${{ env.TOFU_LOG }}
@@ -973,20 +974,20 @@ jobs:
            { sudo mkdir -p "$E2E_ROOT/work" && sudo chown "$(id -u):$(id -g)" "$E2E_ROOT" "$E2E_ROOT/work"; }
          echo "TMPDIR=$E2E_ROOT/work" >> "$GITHUB_ENV"

-      - 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 }}
          path: mulga

-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          ref: ${{ env.GIT_BRANCH }}
          path: mulga/spinifex
@@ -998,25 +999,25 @@ jobs:
        run: bash .github/resolve-sibling-refs.sh
        working-directory: mulga/spinifex

-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          repository: mulgadc/viperblock
          ref: ${{ steps.siblings.outputs.viperblock }}
          path: mulga/viperblock

-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          repository: mulgadc/predastore
          ref: ${{ steps.siblings.outputs.predastore }}
          path: mulga/predastore

-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          repository: mulgadc/northstar
          ref: ${{ steps.siblings.outputs.northstar }}
          path: mulga/northstar

-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          repository: mulgadc/bluebottle
          ref: ${{ steps.siblings.outputs.bluebottle }}
@@ -1151,7 +1152,7 @@ jobs:
                 /tmp/smoke-$GITHUB_RUN_ID.log | tail -1)
          [ -n "$qemu" ] && cp "$qemu" /tmp/cell21-artifacts-$GITHUB_RUN_ID/qemu.log || true

-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@v7.0.2
        if: always()
        with:
          name: e2e-artifacts-cell-21-${{ github.run_id }}
@@ -1220,20 +1221,20 @@ jobs:
          # disks, which is what the tmpfs assertion below is about.
          echo "WORK_DIR=$E2E_ROOT/work/cell22-$GITHUB_RUN_ID" >> "$GITHUB_ENV"

-      - 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 }}
          path: mulga

-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          ref: ${{ env.GIT_BRANCH }}
          path: mulga/spinifex
@@ -1245,25 +1246,25 @@ jobs:
        run: bash .github/resolve-sibling-refs.sh
        working-directory: mulga/spinifex

-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          repository: mulgadc/viperblock
          ref: ${{ steps.siblings.outputs.viperblock }}
          path: mulga/viperblock

-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          repository: mulgadc/predastore
          ref: ${{ steps.siblings.outputs.predastore }}
          path: mulga/predastore

-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          repository: mulgadc/northstar
          ref: ${{ steps.siblings.outputs.northstar }}
          path: mulga/northstar

-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          repository: mulgadc/bluebottle
          ref: ${{ steps.siblings.outputs.bluebottle }}
@@ -1317,7 +1318,7 @@ jobs:
          cp "$WORK_DIR"/*-serial.log /tmp/cell22-artifacts-$GITHUB_RUN_ID/ 2>/dev/null ||
            echo "no per-node serial logs — the run passed and cleaned up after itself"

-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@v7.0.2
        if: always()
        with:
          name: e2e-artifacts-cell-22-${{ github.run_id }}
@@ -1369,7 +1370,7 @@ jobs:
          echo "PERF_RESULTS_ROOT=$E2E_ROOT/predastore-perf-$GITHUB_RUN_ID" >> "$GITHUB_ENV"

      - name: Checkout Spinifex
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
        with:
          path: spinifex

@@ -1384,7 +1385,7 @@ jobs:
        working-directory: spinifex

      - name: Checkout Predastore
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
        with:
          repository: mulgadc/predastore
          ref: ${{ steps.siblings.outputs.predastore }}
@@ -1437,7 +1438,7 @@ jobs:
      # Report-only. The baseline comparison and the -10% gate are mulga-wpjsx;
      # until the run-to-run spread is known from real nights, a threshold would
      # be a guess, and a gate that cries wolf gets muted.
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@v7.0.2
        if: always()
        with:
          name: predastore-perf-${{ github.run_id }}
@@ -1496,7 +1497,7 @@ jobs:
          echo "STRESS_RESULTS_ROOT=$E2E_ROOT/predastore-stress-$GITHUB_RUN_ID" >> "$GITHUB_ENV"

      - name: Checkout Spinifex
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
        with:
          path: spinifex

@@ -1508,7 +1509,7 @@ jobs:
        working-directory: spinifex

      - name: Checkout Predastore
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
        with:
          repository: mulgadc/predastore
          ref: ${{ steps.siblings.outputs.predastore }}
@@ -1563,7 +1564,7 @@ jobs:
          mkdir -p "$STRESS_RESULTS_ROOT"
          make e2e-stress 2>&1 | tee "$STRESS_RESULTS_ROOT/e2e-stress.log"

-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@v7.0.2
        if: always()
        with:
          name: predastore-stress-${{ github.run_id }}
@@ -1600,13 +1601,13 @@ jobs:
    if: always()
    runs-on: ubuntu-26.04
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          sparse-checkout: .github/scripts/e2e-run-summary.py
          sparse-checkout-cone-mode: false

      - name: Collect junit
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@v8.0.2
        with:
          pattern: junit-cell-*-${{ github.run_id }}
          path: junit
@@ -103,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
@@ -157,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

@@ -300,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 }}
@@ -323,18 +323,19 @@ jobs:
      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 }}
@@ -390,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"
@@ -400,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 }}
@@ -444,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

@@ -467,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 }}
@@ -523,7 +524,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-td-${{ github.run_id }}
          path: ${{ env.TOFU_LOG }}
@@ -571,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
@@ -606,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

@@ -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 }}
@@ -737,18 +738,19 @@ jobs:
      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 }}
@@ -804,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"
@@ -814,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 }}
@@ -854,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

@@ -908,7 +910,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-td-${{ github.run_id }}
          path: ${{ env.TOFU_LOG }}
@@ -54,7 +54,7 @@ jobs:
      single_timeout: ${{ steps.budgets.outputs.single_timeout }}
      multi_timeout: ${{ steps.budgets.outputs.multi_timeout }}
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        with:
          path: spinifex
          sparse-checkout: .github/scripts
@@ -142,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
@@ -178,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

@@ -372,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
@@ -512,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"
@@ -522,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 }}
@@ -579,7 +580,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 }}
@@ -642,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
@@ -677,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

@@ -758,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
@@ -965,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"
@@ -975,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 }}
@@ -1035,7 +1037,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 }}
@@ -1105,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 }}
@@ -95,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
@@ -187,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
@@ -243,7 +244,7 @@ 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"
@@ -251,20 +252,20 @@ jobs:
      - 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 }}
@@ -29,13 +29,16 @@ 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 }}
@@ -43,10 +46,10 @@ jobs:

    steps:
      - name: Checkout Code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1

      - name: Set up Go
-        uses: actions/setup-go@v7
+        uses: actions/setup-go@v7.0.0
        with:
          go-version-file: "go.mod"
          # Self-hosted: the module + build cache already persists on local
@@ -80,25 +80,25 @@ jobs:
          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
+      - 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
@@ -116,7 +116,7 @@ jobs:
        run: bash .github/resolve-sibling-refs.sh
        working-directory: spinifex

-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7.0.1
        id: predastore
        with:
          repository: mulgadc/predastore
@@ -366,7 +366,7 @@ jobs:
      # 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
+      - uses: actions/upload-artifact@v7.0.2
        if: always()
        with:
          name: predastore-perf-3node-${{ github.run_id }}
@@ -407,7 +407,7 @@ jobs:

      - name: Upload tofu log
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v7.0.2
        with:
          name: tofu-log-perf3node-${{ github.run_id }}
          path: ${{ env.TOFU_LOG }}
@@ -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:
@@ -94,40 +78,44 @@ 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
@@ -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-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/
@@ -167,14 +186,14 @@ 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 }}
@@ -183,13 +202,13 @@ jobs:

      # 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
+      - 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
@@ -231,6 +250,8 @@ jobs:
  promote:
    needs: [ verify, baremetal ]
    runs-on: ubuntu-26.04
+    permissions:
+      contents: write
    env:
      TAG: ${{ github.ref_name }}
      REPO: ${{ github.repository }}
@@ -263,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 }}
@@ -280,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
@@ -294,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 }}
@@ -302,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 }}
@@ -343,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
@@ -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"
@@ -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') }}
@@ -93,7 +93,7 @@ jobs:
      # 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
+        uses: actions/cache/restore@v6.1.0
        with:
          path: ~/.cache/go-build
          key: gobuild-${{ github.job }}-${{ github.run_id }}
@@ -150,7 +150,7 @@ jobs:

      - name: Save Go build cache
        if: ${{ !cancelled() && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main') }}
-        uses: actions/cache/save@v6
+        uses: actions/cache/save@v6.1.0
        with:
          path: ~/.cache/go-build
          key: gobuild-${{ github.job }}-${{ github.run_id }}
@@ -161,7 +161,7 @@ jobs:

    steps:
      - name: Checkout Spinifex
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
        with:
          path: spinifex

@@ -173,28 +173,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 }}
@@ -204,7 +204,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
@@ -213,7 +213,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') }}
@@ -226,7 +226,7 @@ jobs:
      # 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
+        uses: actions/cache/restore@v6.1.0
        with:
          path: ~/.cache/go-build
          key: gobuild-${{ github.job }}-${{ github.run_id }}
@@ -251,7 +251,7 @@ jobs:

      - name: Save Go build cache
        if: ${{ !cancelled() && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main') }}
-        uses: actions/cache/save@v6
+        uses: actions/cache/save@v6.1.0
        with:
          path: ~/.cache/go-build
          key: gobuild-${{ github.job }}-${{ github.run_id }}
@@ -262,7 +262,7 @@ jobs:

    steps:
      - name: Checkout Spinifex
-        uses: actions/checkout@v7
+        uses: actions/checkout@v7.0.1
        with:
          path: spinifex
          fetch-depth: 2
@@ -275,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 }}
@@ -306,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
@@ -315,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') }}
@@ -328,7 +328,7 @@ jobs:
      # 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
+        uses: actions/cache/restore@v6.1.0
        with:
          path: ~/.cache/go-build
          key: gobuild-${{ github.job }}-${{ github.run_id }}
@@ -338,9 +338,9 @@ 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
@@ -363,7 +363,7 @@ jobs:

      - name: Save Go build cache
        if: ${{ !cancelled() && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main') }}
-        uses: actions/cache/save@v6
+        uses: actions/cache/save@v6.1.0
        with:
          path: ~/.cache/go-build
          key: gobuild-${{ github.job }}-${{ github.run_id }}
@@ -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.0.10
        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
@@ -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
@@ -71,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
@@ -16,6 +16,7 @@ Every AWS call enters through a SigV4-authenticated gateway, is published to NAT
 | [`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).

@@ -53,11 +54,11 @@ 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` (CI pins v2.13.0):
+`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.13.0
+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`.
@@ -75,7 +76,7 @@ The web console additionally needs Node.js 24 and `pnpm`.

 Follow the services with `journalctl -u 'spinifex-*' -f`.

-The web console lives in `spinifex/services/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.
+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

@@ -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 --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)"
@@ -155,7 +155,7 @@ install-microvm: $(MICROVM_ARTIFACTS) ## Install microVM artifacts to /usr/share
 # -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 -j2 -Otarget QUIET=1 lint govulncheck test-cover diff-coverage 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
@@ -220,7 +220,7 @@ aws-model-coverage: generate-aws-model-coverage
 	@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.
@@ -248,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
@@ -259,24 +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)

-# Refresh the README coverage badge. Measured as awesome-go documents
-# (-coverpkg=./... over ./...), with cmd/ entrypoints left out of the total.
-coverage-badge:
-	@echo -e "\n....Measuring whole-module coverage for the README badge...."
-	LOG_IGNORE=1 go test $(GOTESTFLAGS) -timeout 600s -covermode=atomic -coverpkg=./... -coverprofile=coverage-badge.out ./...
-	@grep -v '/cmd/' coverage-badge.out > coverage-badge-nocmd.out
-	@pct=$$(go tool cover -func=coverage-badge-nocmd.out | tail -1 | awk '{print $$NF}' | tr -d '%'); \
-	color=$$(awk -v p="$$pct" 'BEGIN { print (p >= 80) ? "brightgreen" : (p >= 70) ? "yellow" : "red" }'); \
-	sed -i -E "s|badge/coverage-[0-9.]+%25-[a-z]+|badge/coverage-$${pct}%25-$${color}|" README.md; \
-	echo "Coverage $${pct}% ($${color}); README badge updated"
-
 # 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.
@@ -376,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)...."
@@ -390,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.2 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.2.linux-$(GO_ARCH).tar.gz | tar -C /usr/local -xz; \
 	else \
 		echo "Go already installed in /usr/local/go"; \
 	fi
@@ -423,7 +412,7 @@ fix:

 govulncheck:
 	@echo "Running govulncheck..."
-	$(_Q)scripts/run-gate.sh govulncheck go tool govulncheck ./...
+	$(_Q)scripts/run-gate.sh govulncheck scripts/govulncheck-gate.sh
 	@echo "  govulncheck ok"

 # NilAway — advisory nil-panic analysis. Not in preflight due to false positives
@@ -475,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 coverage-badge 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 \
+.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 \
@@ -4,225 +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="https://github.com/mulgadc/spinifex/blob/main/Makefile"><img src="https://img.shields.io/badge/coverage-82.9%25-brightgreen?style=flat-square" alt="Coverage"></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://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>
+  <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 | Q4 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

@@ -230,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.
@@ -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"},
+}
@@ -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())
+			}
+		}
+	}
+}
@@ -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
+}
@@ -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"},
+}
@@ -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
+}
@@ -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)
+	}
+}
@@ -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
+}
@@ -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)
+		}
+	}
+}
@@ -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
+		},
+	},
+}
@@ -1,6 +1,6 @@
 ARG VERSION=dev

-FROM golang:1.27-bookworm AS builder
+FROM golang:1.27.2-bookworm@sha256:5cf287a799e6b94384bad13d16b14904c531f51ba65792237e122ce42b392f61 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)
@@ -7,7 +7,10 @@ import (

 	"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"
 )
@@ -43,10 +46,15 @@ func fail(err error) {
 }

 func compareAll() ([]awsmodel.OperationCoverage, error) {
-	dispatch := gateway.AWSOperationInventory()
+	// 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:
@@ -23,7 +23,7 @@ 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"
 )
@@ -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/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))
 }
@@ -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 (
@@ -18,12 +11,19 @@ import (
 	"syscall"

 	_ "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)
@@ -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"
-)

-// 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)
 }
@@ -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"
-)

-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
+	"github.com/mulgadc/spinifex/spinifex/agents/eks/gatewaypublish"
 )

-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)
 }
@@ -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,225 +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)
 }
@@ -1,76 +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
@@ -97,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)
-	}
-}
@@ -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{
@@ -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,133 +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)
 }
@@ -6,9 +6,9 @@ import (
 	"strings"

 	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
-	"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/spinifex/operator/installer/autoinstall"
+	"github.com/mulgadc/spinifex/spinifex/operator/installer/install"
+	"github.com/mulgadc/spinifex/spinifex/operator/installer/ui"
 )

 func main() {
@@ -1,11 +1,7 @@
-// rds-agent runs inside a Spinifex RDS instance. It registers the VM with the
-// control plane over TLS+SigV4 (never NATS), writes the bootstrap handoff the
-// engine's first-boot script consumes, then heartbeats health and polls for
-// directives.
-//
-// It is the only path by which a secret reaches the VM: the master password is
-// served once, to an authenticated caller. Static config is read from the
-// cloud-init env file /etc/spinifex-rds/agent.env; real env vars override it.
+// Command rds-agent runs inside a Spinifex RDS instance; the implementation is
+// in agents/rds/agent. This binary owns process lifecycle: signal handling,
+// treating a cancelled startup as a clean stop, failure logging and the exit
+// code.
 package main

 import (
@@ -17,23 +13,69 @@ import (
 	"syscall"

 	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
+
+	rdsagent "github.com/mulgadc/spinifex/spinifex/agents/rds/agent"
+	rdsengine "github.com/mulgadc/spinifex/spinifex/domains/rds/engine"
 )

+// version is the agent build version, reported at registration.
+// Overridable via -ldflags "-X main.version=...".
+var version = "dev"
+
+// engineCatalogAdapter composes the agent's narrow EngineCatalog over the
+// control plane's own engine package. This binary is the only place in the
+// agent's dependency graph that imports it.
+type engineCatalogAdapter struct {
+	engine rdsengine.Engine
+}
+
+var _ rdsagent.EngineCatalog = engineCatalogAdapter{}
+
+func (a engineCatalogAdapter) OptionFileName(name string) string {
+	return a.engine.OptionFileName(name)
+}
+
+func (a engineCatalogAdapter) LookupParameter(name string) (rdsagent.CatalogParameter, bool) {
+	spec, ok := a.engine.LookupParameter(name)
+	if !ok {
+		return rdsagent.CatalogParameter{}, false
+	}
+	return rdsagent.CatalogParameter{DataType: spec.DataType, Static: spec.ApplyType == rdsengine.ApplyTypeStatic}, true
+}
+
+func (a engineCatalogAdapter) CatalogParameterNames() []string {
+	return a.engine.CatalogParameterNames()
+}
+
+func (a engineCatalogAdapter) TLSEnforcementParameter() string {
+	return a.engine.TLSEnforcementParameter()
+}
+
+func (a engineCatalogAdapter) ValidateMasterUsername(username string) error {
+	return a.engine.ValidateMasterUsername(username)
+}
+
+func (a engineCatalogAdapter) ValidateUsernameNotReserved(username string) error {
+	return a.engine.ValidateUsernameNotReserved(username)
+}
+
+func lookupEngineCatalog(name string) (rdsagent.EngineCatalog, error) {
+	e, err := rdsengine.LookupEngine(name)
+	if err != nil {
+		return nil, err
+	}
+	return engineCatalogAdapter{engine: e}, nil
+}
+
 func main() {
-	cfg := loadConfig(defaultEnvFile)
+	cfg := rdsagent.LoadConfig(rdsagent.DefaultEnvFile)
+	cfg.AgentVersion = version
+	cfg.EngineCatalog = lookupEngineCatalog

 	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
 	defer stop()

-	// Retried rather than fatal: construction resolves the IMDS credential chain,
-	// so a metadata service that is not answering yet would otherwise end the
-	// process with the engine still down and nothing left to bring it back.
-	var agent *Agent
-	err := retry(ctx, "startup", func(context.Context) error {
-		var err error
-		agent, err = New(cfg)
-		return err
-	})
+	agent, err := rdsagent.Start(ctx, cfg)
 	if err != nil {
 		if errors.Is(err, context.Canceled) {
 			return
@@ -2,9 +2,9 @@ package main

 import (
 	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
-	"github.com/mulgadc/spinifex/cmd/spinifex/cmd"
+	"github.com/mulgadc/spinifex/spinifex/operator/cli"
 )

 func main() {
-	cmd.Execute()
+	cli.Execute()
 }
@@ -37,7 +37,7 @@ import (
 	"syscall"
 	"time"

-	"github.com/mulgadc/spinifex/spinifex/loadgen"
+	"github.com/mulgadc/spinifex/internal/testkit/loadgen"

 	_ "github.com/mulgadc/bluebottle/pkg/fipsboot"
 )
@@ -0,0 +1,29 @@
+# Cluster v1 contracts
+
+This package owns the versioned cluster control-plane wire contracts. It is
+not an AWS tenant-facing API: it lets platform consumers identify responding
+daemon nodes and inspect their health.
+
+`NodesDiscoverSubject` retains the deployed `spinifex.nodes.discover` route.
+`NodeDiscoverResponse.Node` is the node identifier used for responder-set
+coverage. Do not change either incompatibly in this package; add a new version
+when a wire change is required.
+
+`NodeHealthSubject` retains the deployed per-node NATS route, while
+`NodeHealthResponse` is also the daemon HTTPS `/health` representation. Do not
+change their subject or JSON shape incompatibly in this package; add a new
+version when a wire change is required.
+
+`NodeVMsSubject` retains the deployed `spinifex.node.vms` fan-out route.
+`NodeVMsResponse` is the VM inventory reply used by the SPX operator CLI and
+by EKS host lookup. It is distinct from node status and capacity reporting:
+do not add scheduling or physical-GPU inventory merely because those callers
+also inspect nodes. Do not change its subject or JSON shape incompatibly; add
+a new version when a wire change is required.
+
+`NodeStatusSubject` retains the deployed `spinifex.node.status` fan-out route.
+`NodeStatusResponse` carries daemon-reported status, schedulable capacity and
+physical-GPU inventory for the SPX operator CLI and EC2/EKS placement callers.
+It is an observation contract, not the owner of capacity, scheduling or GPU
+allocation policy. Do not change its subject or JSON shape incompatibly; add
+a new version when a wire change is required.
@@ -0,0 +1,16 @@
+// Package clusterv1 defines version 1 of the cluster control-plane contract.
+// Its NATS subjects and JSON fields are wire compatibility, not implementation
+// details of a daemon or consumer.
+package clusterv1
+
+const (
+	// NodesDiscoverSubject fans out a membership discovery request to every
+	// active daemon. Its reply payload is NodeDiscoverResponse.
+	NodesDiscoverSubject = "spinifex.nodes.discover"
+)
+
+// NodeDiscoverResponse identifies one daemon that responded to a membership
+// discovery request.
+type NodeDiscoverResponse struct {
+	Node string `json:"node"`
+}
@@ -0,0 +1,18 @@
+package clusterv1
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNodeDiscoverResponseJSONContract(t *testing.T) {
+	data, err := json.Marshal(NodeDiscoverResponse{Node: "node-a"})
+	require.NoError(t, err)
+	require.JSONEq(t, `{"node":"node-a"}`, string(data))
+}
+
+func TestNodesDiscoverSubject(t *testing.T) {
+	require.Equal(t, "spinifex.nodes.discover", NodesDiscoverSubject)
+}
@@ -0,0 +1,23 @@
+package clusterv1
+
+import "fmt"
+
+// NodeHealthSubject returns the NATS route for one daemon's health response.
+// It intentionally performs no node-ID validation: callers have always
+// supplied the configured node identifier directly to NATS, and this
+// structural move must preserve that behaviour.
+func NodeHealthSubject(node string) string {
+	return fmt.Sprintf("spinifex.admin.%s.health", node)
+}
+
+// NodeHealthResponse is the daemon health representation returned by both the
+// per-node NATS health route and the daemon HTTPS /health endpoint.
+type NodeHealthResponse struct {
+	Node          string            `json:"node"`
+	Status        string            `json:"status"`
+	ConfigHash    string            `json:"config_hash"`
+	Epoch         uint64            `json:"epoch"`
+	Uptime        int64             `json:"uptime"`
+	Services      []string          `json:"services"`
+	ServiceHealth map[string]string `json:"service_health,omitempty"`
+}
@@ -0,0 +1,36 @@
+package clusterv1
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNodeHealthResponseJSONContract(t *testing.T) {
+	data, err := json.Marshal(NodeHealthResponse{
+		Node:       "node-a",
+		Status:     "running",
+		ConfigHash: "abc123",
+		Epoch:      7,
+		Uptime:     42,
+		Services:   []string{"nats", "spinifex"},
+		ServiceHealth: map[string]string{
+			"nats": "ok",
+		},
+	})
+	require.NoError(t, err)
+	require.JSONEq(t, `{
+		"node":"node-a",
+		"status":"running",
+		"config_hash":"abc123",
+		"epoch":7,
+		"uptime":42,
+		"services":["nats","spinifex"],
+		"service_health":{"nats":"ok"}
+	}`, string(data))
+}
+
+func TestNodeHealthSubject(t *testing.T) {
+	require.Equal(t, "spinifex.admin.node-a.health", NodeHealthSubject("node-a"))
+}
@@ -0,0 +1,44 @@
+package clusterv1
+
+const (
+	// NodeVMsSubject fans out a request for each responding daemon's VM
+	// inventory. Its reply payload is NodeVMsResponse.
+	NodeVMsSubject = "spinifex.node.vms"
+)
+
+// VMGPUInfo describes one GPU attached to a VM in a NodeVMsResponse.
+type VMGPUInfo struct {
+	Model      string `json:"model"`
+	VRAMMiB    int64  `json:"vram_mib"`
+	PCIAddress string `json:"pci_address,omitempty"` // whole-GPU passthrough only
+	Profile    string `json:"profile,omitempty"`     // MIG profile name; empty for whole-GPU
+	MdevPath   string `json:"mdev_path,omitempty"`   // MIG only
+}
+
+// VMInfo describes one VM in a node's inventory response.
+type VMInfo struct {
+	InstanceID   string  `json:"instance_id"`
+	Status       string  `json:"status"`
+	InstanceType string  `json:"instance_type"`
+	VCPU         int     `json:"vcpu"`
+	MemoryGB     float64 `json:"memory_gb"`
+	LaunchTime   int64   `json:"launch_time"`
+	// ManagedBy is the Spinifex platform component that owns this VM
+	// (e.g. "elbv2"). Empty for customer VMs. The UI uses this to filter
+	// system-managed resources out of customer-facing listings.
+	ManagedBy string      `json:"managed_by,omitempty"`
+	GPUs      []VMGPUInfo `json:"gpus,omitempty"`
+	// Health is a display label for instance health: "ok", "impaired",
+	// "recovering", or "-" for non-running VMs. CrashCount is the lifetime
+	// crash tally within the current restart window.
+	Health     string `json:"health,omitempty"`
+	CrashCount int    `json:"crash_count,omitempty"`
+}
+
+// NodeVMsResponse is one daemon's reply on NodeVMsSubject. The subject fans
+// out, so callers collect one response per responding node.
+type NodeVMsResponse struct {
+	Node string   `json:"node"`
+	Host string   `json:"host"`
+	VMs  []VMInfo `json:"vms"`
+}
@@ -0,0 +1,60 @@
+package clusterv1
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNodeVMsResponseJSONContract(t *testing.T) {
+	data, err := json.Marshal(NodeVMsResponse{
+		Node: "node-a",
+		Host: "10.0.0.1",
+		VMs: []VMInfo{{
+			InstanceID:   "i-abc123",
+			Status:       "running",
+			InstanceType: "t3.small",
+			VCPU:         2,
+			MemoryGB:     2.0,
+			LaunchTime:   1736935200,
+			ManagedBy:    "elbv2",
+			GPUs: []VMGPUInfo{{
+				Model:      "NVIDIA A10",
+				VRAMMiB:    23028,
+				PCIAddress: "0000:01:00.0",
+				Profile:    "MIG 1g.6gb",
+				MdevPath:   "/sys/bus/mdev/devices/example",
+			}},
+			Health:     "ok",
+			CrashCount: 2,
+		}},
+	})
+	require.NoError(t, err)
+	require.JSONEq(t, `{
+		"node":"node-a",
+		"host":"10.0.0.1",
+		"vms":[{
+			"instance_id":"i-abc123",
+			"status":"running",
+			"instance_type":"t3.small",
+			"vcpu":2,
+			"memory_gb":2,
+			"launch_time":1736935200,
+			"managed_by":"elbv2",
+			"gpus":[{
+				"model":"NVIDIA A10",
+				"vram_mib":23028,
+				"pci_address":"0000:01:00.0",
+				"profile":"MIG 1g.6gb",
+				"mdev_path":"/sys/bus/mdev/devices/example"
+			}],
+			"health":"ok",
+			"crash_count":2
+		}]
+	}`, string(data))
+}
+
+func TestNodeVMsSubject(t *testing.T) {
+	require.Equal(t, "spinifex.node.vms", NodeVMsSubject)
+}
@@ -1,9 +1,10 @@
-package types
+package clusterv1

-// NodeDiscoverResponse is the response for node discovery requests.
-type NodeDiscoverResponse struct {
-	Node string `json:"node"`
-}
+const (
+	// NodeStatusSubject fans out a request for each responding daemon's status
+	// and schedulable-capacity snapshot. Its reply payload is NodeStatusResponse.
+	NodeStatusSubject = "spinifex.node.status"
+)

 // GPUSliceInfo describes a single MIG slice within a physical GPU.
 type GPUSliceInfo struct {
@@ -27,17 +28,9 @@ type GPUInfo struct {
 	Slices     []GPUSliceInfo `json:"slices,omitempty"`
 }

-// VMGPUInfo describes one GPU attached to a VM.
-type VMGPUInfo struct {
-	Model      string `json:"model"`
-	VRAMMiB    int64  `json:"vram_mib"`
-	PCIAddress string `json:"pci_address,omitempty"` // whole-GPU passthrough only
-	Profile    string `json:"profile,omitempty"`     // MIG profile name; empty for whole-GPU
-	MdevPath   string `json:"mdev_path,omitempty"`   // MIG only
-}
-
-// NodeStatusResponse is returned by the spinifex.node.status NATS topic (fan-out).
-// Schedulable capacity = TotalVCPU - ReservedVCPU - AllocVCPU (same for memory).
+// NodeStatusResponse is one daemon's reply on NodeStatusSubject. Schedulable
+// capacity = TotalVCPU - ReservedVCPU - AllocVCPU (and the same for memory).
+// The subject fans out, so callers collect one response per responding node.
 type NodeStatusResponse struct {
 	Node           string            `json:"node"`
 	Status         string            `json:"status"`
@@ -81,30 +74,3 @@ type InstanceTypeCap struct {
 	MemoryGB  float64 `json:"memory_gb"`
 	Available int     `json:"available"`
 }
-
-// VMInfo describes a single VM for the cluster stats CLI.
-type VMInfo struct {
-	InstanceID   string  `json:"instance_id"`
-	Status       string  `json:"status"`
-	InstanceType string  `json:"instance_type"`
-	VCPU         int     `json:"vcpu"`
-	MemoryGB     float64 `json:"memory_gb"`
-	LaunchTime   int64   `json:"launch_time"`
-	// ManagedBy is the Spinifex platform component that owns this VM
-	// (e.g. "elbv2"). Empty for customer VMs. The UI uses this to filter
-	// system-managed resources out of customer-facing listings.
-	ManagedBy string      `json:"managed_by,omitempty"`
-	GPUs      []VMGPUInfo `json:"gpus,omitempty"`
-	// Health is a display label for instance health: "ok", "impaired",
-	// "recovering", or "-" for non-running VMs. CrashCount is the lifetime
-	// crash tally within the current restart window.
-	Health     string `json:"health,omitempty"`
-	CrashCount int    `json:"crash_count,omitempty"`
-}
-
-// NodeVMsResponse is returned by the spinifex.node.vms NATS topic (fan-out).
-type NodeVMsResponse struct {
-	Node string   `json:"node"`
-	Host string   `json:"host"`
-	VMs  []VMInfo `json:"vms"`
-}
@@ -0,0 +1,81 @@
+package clusterv1
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNodeStatusResponseJSONContract(t *testing.T) {
+	data, err := json.Marshal(NodeStatusResponse{
+		Node:           "node-a",
+		Status:         "Ready",
+		Host:           "10.0.0.1",
+		Region:         "ap-southeast-2",
+		AZ:             "ap-southeast-2a",
+		Uptime:         42,
+		Services:       []string{"nats", "spinifex"},
+		TotalVCPU:      16,
+		TotalMemGB:     64,
+		ReservedVCPU:   2,
+		ReservedMemGB:  4,
+		AllocVCPU:      4,
+		AllocMemGB:     8,
+		TotalGPUs:      1,
+		AllocGPUs:      1,
+		GPUCapable:     true,
+		GPUPassthrough: true,
+		GPUModels:      []string{"NVIDIA A10"},
+		GPUs: []GPUInfo{{
+			PCIAddress: "0000:01:00.0",
+			Model:      "NVIDIA A10",
+			VRAMMiB:    23028,
+			MIGEnabled: true,
+			MIGProfile: "1g.6gb",
+			InstanceID: "i-abc123",
+			Slices: []GPUSliceInfo{{
+				GIID:       1,
+				Profile:    "1g.6gb",
+				VRAMMiB:    6144,
+				MdevPath:   "/sys/bus/mdev/devices/example",
+				InstanceID: "i-abc123",
+			}},
+		}},
+		VMCount: 1,
+		InstanceTypes: []InstanceTypeCap{{
+			Name: "g5.xlarge", VCPU: 4, MemoryGB: 16, Available: 2,
+		}},
+		NATSRole:       "leader",
+		PredastoreRole: "follower",
+		OVNNBRole:      "leader",
+		OVNSBRole:      "follower",
+	})
+	require.NoError(t, err)
+	require.JSONEq(t, `{
+		"node":"node-a", "status":"Ready", "host":"10.0.0.1",
+		"region":"ap-southeast-2", "az":"ap-southeast-2a", "uptime":42,
+		"services":["nats","spinifex"],
+		"total_vcpu":16, "total_mem_gb":64,
+		"reserved_vcpu":2, "reserved_mem_gb":4,
+		"alloc_vcpu":4, "alloc_mem_gb":8,
+		"total_gpus":1, "alloc_gpus":1,
+		"gpu_capable":true, "gpu_passthrough":true, "gpu_models":["NVIDIA A10"],
+		"gpus":[{
+			"pci_address":"0000:01:00.0", "model":"NVIDIA A10", "vram_mib":23028,
+			"mig_enabled":true, "mig_profile":"1g.6gb", "instance_id":"i-abc123",
+			"slices":[{
+				"gi_id":1, "profile":"1g.6gb", "vram_mib":6144,
+				"mdev_path":"/sys/bus/mdev/devices/example", "instance_id":"i-abc123"
+			}]
+		}],
+		"vm_count":1,
+		"instance_types":[{"name":"g5.xlarge", "vcpu":4, "memory_gb":16, "available":2}],
+		"nats_role":"leader", "predastore_role":"follower",
+		"ovn_nb_role":"leader", "ovn_sb_role":"follower"
+	}`, string(data))
+}
+
+func TestNodeStatusSubject(t *testing.T) {
+	require.Equal(t, "spinifex.node.status", NodeStatusSubject)
+}
@@ -0,0 +1,62 @@
+# EC2 instance-command contract, version 1
+
+This package owns the cross-process contract used to direct a command to the
+node that owns a running EC2 instance. It is not an in-process service
+interface or the owner of instance state.
+
+## Route and purpose
+
+The subject is `ec2.cmd.<instance-id>`. It is request/reply, and the daemon
+that hosts that instance's QEMU process is the only subscriber. This route
+exists because lifecycle operations such as start, stop, terminate, volume
+attach/detach and ENI attach/detach must reach that one process; sending them
+through the normal daemon queue group could select a different node.
+
+`InstanceCommandSubject` constructs a targeted subject. The corresponding
+subscription and permission pattern is `ec2.cmd.*`: the `*` deliberately
+matches exactly one final instance-ID token, not an arbitrary descendant.
+
+## Compatibility boundary
+
+`EC2InstanceCommand`, its nested data objects, their JSON field names and the
+subject shape are wire compatibility. Callers and receivers must use this
+package rather than rebuild those details. `commands_test.go` preserves the
+version-1 JSON shape and subject form.
+
+This package owns shared command payloads and the drain-volume response. It
+does not define every action's reply body, authorize the request, store EC2
+state or implement NATS transport. Those remain responsibilities of the EC2
+domain and its runtime composition.
+
+Any incompatible subject or payload change requires an explicit versioned
+contract or an approved compatibility plan; it is not a package refactor.
+
+## Default VPC request
+
+`EnsureDefaultVpcSubject` (`ec2.EnsureDefaultVpc`) is the request/reply route on which the gateway's account creation asks a daemon in the `spinifex-workers` queue group to build the account's default VPC.
+Only the subject is owned here today.
+The request (`account_id`) and reply (`vpc_id`, `error`) bodies are still declared as anonymous structs on each side; moving them into this package is a contract change that needs its own characterization first.
+
+## Platform inventory
+
+`PlatformInventorySubject` (`ec2.v1.PlatformInventory`) is a request/reply route on which a daemon in the `spinifex-workers` queue group reports one account's key pairs, placement groups, launch templates and their `ec2-tags` entries from the EC2 owner stores.
+EC2 owns it: `domains/ec2/accountinventory` produces the reply and the daemon serves it; the only consumer today is `accountteardown`, which binds an adapter but does not call it.
+
+The request names the account in its body (`account_id`, a 12-digit ID) and may carry an opaque `correlation_ref` that is echoed for logs.
+The daemon ignores `X-Account-ID` for this subject.
+Neither field grants anything: the subject is read-only, writes to no store, and its reply is never authority to delete.
+
+The reply has one `kinds` entry per kind (`key-pair`, `placement-group`, `launch-template`, `tag-index`) with a status and scan start and end times.
+The times are zero when no owner scan ran: a consumer-synthesised `scan-incomplete` report for no responder, a timeout or a transport failure carries zero timestamps and must not be read as a scan.
+`observed-clean-at-scan-time` means every store for that kind was read completely and held nothing at scan time; writers are not fenced, so it is a snapshot and never evidence of absence.
+`items` carry only a resource ID, kind and disposition (`live`, `dependency-held`, or tag-index `residue`), which are the identities the per-kind Describe subjects already return.
+A `dependency-held` placement group does not name its member instances, which may be stale and are not exposed by the existing subjects.
+Records no existing subject exposes (public-key objects without metadata, launch-template version bodies and name-index entries without a header, and every unreadable record) appear only as aggregate `counts` per kind, disposition and class.
+The reply never carries an object key, raw KV key, key or template name, tag key or value, public-key bytes, launch-template data, user data, record body or store error text; `incomplete_reasons` are fixed categories.
+
+### Compatibility boundary
+
+The subject name carries the contract major; `platform_inventory_test.go` preserves the version-1 JSON shape and wire vocabulary.
+Producer and consumer are in the coordinated Spinifex release, so the window is N and N-1.
+A daemon that predates the subject has no subscription, so the request gets no responder; the consumer treats no responder, a timeout, an error reply, an undecodable reply, a reply for another account, and a missing, repeated or unknown-status kind as `scan-incomplete`, never clean.
+An incompatible change to the subject, fields or vocabulary needs a new major.
@@ -1,4 +1,26 @@
-package types
+// Package ec2v1 defines version 1 of the cross-process EC2 instance-command
+// contract. These payloads travel on ec2.cmd.<instance-id>; their JSON fields
+// are wire compatibility, not an implementation detail of a caller.
+package ec2v1
+
+const (
+	// InstanceCommandSubjectPrefix is the NATS subject family whose final token
+	// identifies the instance-owning daemon.
+	InstanceCommandSubjectPrefix = "ec2.cmd."
+
+	// InstanceCommandSubjectWildcard matches exactly one instance-ID token in
+	// this contract family. It is the NATS permission/subscription pattern for
+	// the per-instance command route, rather than the broader descendant match.
+	InstanceCommandSubjectWildcard = InstanceCommandSubjectPrefix + "*"
+)
+
+// InstanceCommandSubject returns the targeted command subject for instanceID.
+// It intentionally performs no validation: callers have always supplied the
+// already-validated instance identifier directly to NATS, and this structural
+// move must not change that behaviour.
+func InstanceCommandSubject(instanceID string) string {
+	return InstanceCommandSubjectPrefix + instanceID
+}

 // EC2InstanceCommand is the NATS wire format for EC2 instance commands
 // (stop, terminate, start, attach/detach-volume, attach/detach-eni).
@@ -0,0 +1,85 @@
+package ec2v1
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestEC2InstanceCommandJSONContract(t *testing.T) {
+	command := EC2InstanceCommand{
+		ID: "i-0123456789abcdef0",
+		Attributes: EC2CommandAttributes{
+			StopInstance:                true,
+			TerminateInstance:           true,
+			StartInstance:               true,
+			AttachVolume:                true,
+			DetachVolume:                true,
+			DrainVolume:                 true,
+			RebootInstance:              true,
+			AttachENI:                   true,
+			DetachENI:                   true,
+			AssociateIamInstanceProfile: true,
+			SetSpotLineage:              true,
+			SetInstanceTags:             true,
+			RemoveInstanceTags:          true,
+			SetInstanceMonitoring:       true,
+		},
+		AttachVolumeData:          &AttachVolumeData{VolumeID: "vol-1", Device: "/dev/sdf"},
+		DetachVolumeData:          &DetachVolumeData{VolumeID: "vol-2", Device: "/dev/sdg", Force: true},
+		DrainVolumeData:           &DrainVolumeData{VolumeID: "vol-3"},
+		AttachENIData:             &AttachENIData{NetworkInterfaceID: "eni-1", DeviceIndex: 2},
+		DetachENIData:             &DetachENIData{AttachmentID: "eni-attach-1", Force: true},
+		IamProfileAssociationData: &IamProfileAssociationData{InstanceProfileArn: "arn:aws:iam::123456789012:instance-profile/example"},
+		SpotLineageData:           &SpotLineageData{SpotInstanceRequestId: "sir-1"},
+		InstanceTagsData:          &InstanceTagsData{Tags: map[string]string{"Name": "example"}, TagKeys: []string{"old"}},
+		InstanceMonitoringData:    &InstanceMonitoringData{Enabled: true},
+	}
+
+	data, err := json.Marshal(command)
+	require.NoError(t, err)
+	require.JSONEq(t, `{
+		"id": "i-0123456789abcdef0",
+		"attributes": {
+			"stop_instance": true,
+			"delete_instance": true,
+			"start_instance": true,
+			"attach_volume": true,
+			"detach_volume": true,
+			"drain_volume": true,
+			"reboot_instance": true,
+			"attach_eni": true,
+			"detach_eni": true,
+			"associate_iam_instance_profile": true,
+			"set_spot_lineage": true,
+			"set_instance_tags": true,
+			"remove_instance_tags": true,
+			"set_instance_monitoring": true
+		},
+		"attach_volume_data": {"volume_id": "vol-1", "device": "/dev/sdf"},
+		"detach_volume_data": {"volume_id": "vol-2", "device": "/dev/sdg", "force": true},
+		"drain_volume_data": {"volume_id": "vol-3"},
+		"attach_eni_data": {"network_interface_id": "eni-1", "device_index": 2},
+		"detach_eni_data": {"attachment_id": "eni-attach-1", "force": true},
+		"iam_profile_association_data": {"instance_profile_arn": "arn:aws:iam::123456789012:instance-profile/example"},
+		"spot_lineage_data": {"spot_instance_request_id": "sir-1"},
+		"instance_tags_data": {"tags": {"Name": "example"}, "tag_keys": ["old"]},
+		"instance_monitoring_data": {"enabled": true}
+	}`, string(data))
+}
+
+func TestDrainVolumeResponseJSONContract(t *testing.T) {
+	data, err := json.Marshal(DrainVolumeResponse{
+		VolumeID: "vol-1",
+		Status:   DrainVolumeStatusDrained,
+	})
+	require.NoError(t, err)
+	require.JSONEq(t, `{"volume_id":"vol-1","status":"drained"}`, string(data))
+	require.Equal(t, "not-running", DrainVolumeStatusNotRunning)
+}
+
+func TestInstanceCommandSubjects(t *testing.T) {
+	require.Equal(t, "ec2.cmd.i-0123456789abcdef0", InstanceCommandSubject("i-0123456789abcdef0"))
+	require.Equal(t, "ec2.cmd.*", InstanceCommandSubjectWildcard)
+}
@@ -0,0 +1,6 @@
+package ec2v1
+
+// EnsureDefaultVpcSubject is the request/reply subject on which the daemon
+// builds an account's default VPC and acknowledges, so the gateway and the
+// daemon share the route without importing each other.
+const EnsureDefaultVpcSubject = "ec2.EnsureDefaultVpc"
@@ -0,0 +1,15 @@
+package ec2v1_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	ec2v1 "github.com/mulgadc/spinifex/contracts/ec2/v1"
+)
+
+// The gateway's CreateAccount request and the daemon's subscription meet on
+// this literal; a deployed daemon and gateway of different builds must agree.
+func TestEnsureDefaultVpcSubject(t *testing.T) {
+	require.Equal(t, "ec2.EnsureDefaultVpc", ec2v1.EnsureDefaultVpcSubject)
+}
@@ -0,0 +1,123 @@
+package ec2v1
+
+import "time"
+
+// PlatformInventorySubject is the request/reply subject on which a daemon in
+// the spinifex-workers queue group reports one account's key pairs, placement
+// groups, launch templates and their tag-index entries. It never writes.
+const PlatformInventorySubject = "ec2.v1.PlatformInventory"
+
+// Kinds reported by a platform inventory. The tag index is its own kind
+// because it is a separate store with its own completeness.
+const (
+	PlatformKindKeyPair        = "key-pair"
+	PlatformKindPlacementGroup = "placement-group"
+	PlatformKindLaunchTemplate = "launch-template"
+	PlatformKindTagIndex       = "tag-index"
+)
+
+// PlatformKinds lists every kind a complete reply reports, in reply order.
+func PlatformKinds() []string {
+	return []string{PlatformKindKeyPair, PlatformKindPlacementGroup, PlatformKindLaunchTemplate, PlatformKindTagIndex}
+}
+
+// Per-kind statuses. Only PlatformStatusObservedClean says a kind's stores
+// were read completely and held nothing, and only at scan time: writers are
+// not fenced, so it is a snapshot and never evidence of absence.
+const (
+	PlatformStatusObservedClean  = "observed-clean-at-scan-time"
+	PlatformStatusRecordsFound   = "records-found"
+	PlatformStatusScanIncomplete = "scan-incomplete"
+)
+
+// Item and count dispositions. A store failure is reported once per kind as
+// PlatformStatusScanIncomplete rather than per record.
+const (
+	PlatformDispositionLive           = "live"
+	PlatformDispositionResidue        = "residue"
+	PlatformDispositionUnreadable     = "unreadable"
+	PlatformDispositionDependencyHeld = "dependency-held"
+)
+
+// Record classes that are reported only as aggregate counts.
+const (
+	PlatformClassPublicKeyWithoutMetadata  = "public-key-object-without-metadata"
+	PlatformClassPublicKeyUnresolved       = "public-key-object-unresolved"
+	PlatformClassUnreadableRecord          = "unreadable-record"
+	PlatformClassVersionBodyWithoutHeader  = "version-body-without-header"
+	PlatformClassNameIndexWithoutHeader    = "name-index-without-header"
+	PlatformClassUnrecognisedTemplateEntry = "unrecognised-template-entry"
+)
+
+// Generic reasons a kind is PlatformStatusScanIncomplete. They are categories,
+// never store error text, which can quote stored content.
+const (
+	PlatformReasonStoreListFailed        = "store-list-failed"
+	PlatformReasonRecordReadFailed       = "record-read-failed"
+	PlatformReasonOwnerRecordsUnresolved = "owner-records-unresolved"
+	PlatformReasonNoResponder            = "no-responder"
+	PlatformReasonTimeout                = "timeout"
+	PlatformReasonTransportFailed        = "transport-failed"
+	PlatformReasonErrorReply             = "error-reply"
+	PlatformReasonInvalidReply           = "invalid-reply"
+	PlatformReasonKindNotReported        = "kind-not-reported"
+)
+
+// PlatformInventoryRequest asks for one account's platform inventory.
+// CorrelationRef is an opaque caller reference echoed for logs; it grants
+// nothing and is never a fence or authority to write.
+type PlatformInventoryRequest struct {
+	AccountID      string `json:"account_id"`
+	CorrelationRef string `json:"correlation_ref,omitempty"`
+}
+
+// PlatformInventoryReply carries per-kind status, the identities a direct
+// caller of the per-kind Describe subjects can already read, and counts for
+// every record class those subjects do not expose. It carries no record
+// keys, names, tags, key material, template data or record bodies.
+type PlatformInventoryReply struct {
+	AccountID      string                `json:"account_id"`
+	CorrelationRef string                `json:"correlation_ref,omitempty"`
+	Kinds          []PlatformKindReport  `json:"kinds"`
+	Items          []PlatformItem        `json:"items,omitempty"`
+	Counts         []PlatformRecordCount `json:"counts,omitempty"`
+}
+
+// PlatformKindReport is one kind's scan status and when its scan ran. The
+// timestamps are zero when no owner scan ran, as in a consumer-synthesised
+// scan-incomplete report for no responder, a timeout or a transport failure.
+type PlatformKindReport struct {
+	Kind              string    `json:"kind"`
+	Status            string    `json:"status"`
+	IncompleteReasons []string  `json:"incomplete_reasons,omitempty"`
+	ScanStartedAt     time.Time `json:"scan_started_at"`
+	ScanEndedAt       time.Time `json:"scan_ended_at"`
+}
+
+// PlatformItem is one resource by its AWS resource ID. A dependency-held
+// placement group does not name its member instances.
+type PlatformItem struct {
+	ResourceID  string `json:"resource_id"`
+	Kind        string `json:"kind"`
+	Disposition string `json:"disposition"`
+}
+
+// PlatformRecordCount is the number of records of one class in one kind.
+type PlatformRecordCount struct {
+	Kind        string `json:"kind"`
+	Disposition string `json:"disposition"`
+	Class       string `json:"class"`
+	Count       int    `json:"count"`
+}
+
+// IncompletePlatformInventory is the reply a consumer substitutes when no
+// usable answer arrived: every kind is scan-incomplete for reason.
+func IncompletePlatformInventory(accountID, correlationRef, reason string) PlatformInventoryReply {
+	reply := PlatformInventoryReply{AccountID: accountID, CorrelationRef: correlationRef}
+	for _, kind := range PlatformKinds() {
+		reply.Kinds = append(reply.Kinds, PlatformKindReport{
+			Kind: kind, Status: PlatformStatusScanIncomplete, IncompleteReasons: []string{reason},
+		})
+	}
+	return reply
+}
@@ -0,0 +1,102 @@
+package ec2v1
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestPlatformInventorySubject(t *testing.T) {
+	require.Equal(t, "ec2.v1.PlatformInventory", PlatformInventorySubject)
+}
+
+func TestPlatformInventoryRequestJSONContract(t *testing.T) {
+	data, err := json.Marshal(PlatformInventoryRequest{AccountID: "111122223333", CorrelationRef: "req-1"})
+	require.NoError(t, err)
+	require.JSONEq(t, `{"account_id":"111122223333","correlation_ref":"req-1"}`, string(data))
+
+	data, err = json.Marshal(PlatformInventoryRequest{AccountID: "111122223333"})
+	require.NoError(t, err)
+	require.JSONEq(t, `{"account_id":"111122223333"}`, string(data))
+}
+
+func TestPlatformInventoryReplyJSONContract(t *testing.T) {
+	start := time.Date(2026, 10, 16, 1, 2, 3, 0, time.UTC)
+	reply := PlatformInventoryReply{
+		AccountID:      "111122223333",
+		CorrelationRef: "req-1",
+		Kinds: []PlatformKindReport{
+			{Kind: PlatformKindKeyPair, Status: PlatformStatusObservedClean, ScanStartedAt: start, ScanEndedAt: start.Add(time.Second)},
+			{Kind: PlatformKindPlacementGroup, Status: PlatformStatusRecordsFound, ScanStartedAt: start, ScanEndedAt: start},
+			{Kind: PlatformKindLaunchTemplate, Status: PlatformStatusScanIncomplete, IncompleteReasons: []string{PlatformReasonStoreListFailed}, ScanStartedAt: start, ScanEndedAt: start},
+			{Kind: PlatformKindTagIndex, Status: PlatformStatusRecordsFound, ScanStartedAt: start, ScanEndedAt: start},
+		},
+		Items: []PlatformItem{
+			{ResourceID: "pg-0held", Kind: PlatformKindPlacementGroup, Disposition: PlatformDispositionDependencyHeld},
+			{ResourceID: "lt-0gone", Kind: PlatformKindTagIndex, Disposition: PlatformDispositionResidue},
+		},
+		Counts: []PlatformRecordCount{
+			{Kind: PlatformKindKeyPair, Disposition: PlatformDispositionResidue, Class: PlatformClassPublicKeyWithoutMetadata, Count: 2},
+		},
+	}
+
+	data, err := json.Marshal(reply)
+	require.NoError(t, err)
+	require.JSONEq(t, `{
+		"account_id": "111122223333",
+		"correlation_ref": "req-1",
+		"kinds": [
+			{"kind": "key-pair", "status": "observed-clean-at-scan-time", "scan_started_at": "2026-10-16T01:02:03Z", "scan_ended_at": "2026-10-16T01:02:04Z"},
+			{"kind": "placement-group", "status": "records-found", "scan_started_at": "2026-10-16T01:02:03Z", "scan_ended_at": "2026-10-16T01:02:03Z"},
+			{"kind": "launch-template", "status": "scan-incomplete", "incomplete_reasons": ["store-list-failed"], "scan_started_at": "2026-10-16T01:02:03Z", "scan_ended_at": "2026-10-16T01:02:03Z"},
+			{"kind": "tag-index", "status": "records-found", "scan_started_at": "2026-10-16T01:02:03Z", "scan_ended_at": "2026-10-16T01:02:03Z"}
+		],
+		"items": [
+			{"resource_id": "pg-0held", "kind": "placement-group", "disposition": "dependency-held"},
+			{"resource_id": "lt-0gone", "kind": "tag-index", "disposition": "residue"}
+		],
+		"counts": [
+			{"kind": "key-pair", "disposition": "residue", "class": "public-key-object-without-metadata", "count": 2}
+		]
+	}`, string(data))
+}
+
+// The wire values of every status, disposition, class and reason.
+func TestPlatformInventoryVocabulary(t *testing.T) {
+	require.Equal(t, []string{"key-pair", "placement-group", "launch-template", "tag-index"}, PlatformKinds())
+	require.Equal(t, []string{"live", "residue", "unreadable", "dependency-held"},
+		[]string{PlatformDispositionLive, PlatformDispositionResidue, PlatformDispositionUnreadable, PlatformDispositionDependencyHeld})
+	require.Equal(t, []string{
+		"public-key-object-without-metadata", "public-key-object-unresolved", "unreadable-record",
+		"version-body-without-header", "name-index-without-header", "unrecognised-template-entry",
+	}, []string{
+		PlatformClassPublicKeyWithoutMetadata, PlatformClassPublicKeyUnresolved, PlatformClassUnreadableRecord,
+		PlatformClassVersionBodyWithoutHeader, PlatformClassNameIndexWithoutHeader, PlatformClassUnrecognisedTemplateEntry,
+	})
+	require.Equal(t, []string{
+		"store-list-failed", "record-read-failed", "owner-records-unresolved", "no-responder",
+		"timeout", "transport-failed", "error-reply", "invalid-reply", "kind-not-reported",
+	}, []string{
+		PlatformReasonStoreListFailed, PlatformReasonRecordReadFailed, PlatformReasonOwnerRecordsUnresolved, PlatformReasonNoResponder,
+		PlatformReasonTimeout, PlatformReasonTransportFailed, PlatformReasonErrorReply, PlatformReasonInvalidReply, PlatformReasonKindNotReported,
+	})
+}
+
+// A substituted reply never reports a kind clean.
+func TestIncompletePlatformInventoryMarksEveryKindIncomplete(t *testing.T) {
+	reply := IncompletePlatformInventory("111122223333", "req-1", PlatformReasonNoResponder)
+	require.Equal(t, "111122223333", reply.AccountID)
+	require.Equal(t, "req-1", reply.CorrelationRef)
+	require.Len(t, reply.Kinds, len(PlatformKinds()))
+	for i, kind := range PlatformKinds() {
+		require.Equal(t, kind, reply.Kinds[i].Kind)
+		require.Equal(t, PlatformStatusScanIncomplete, reply.Kinds[i].Status)
+		require.Equal(t, []string{PlatformReasonNoResponder}, reply.Kinds[i].IncompleteReasons)
+		require.True(t, reply.Kinds[i].ScanStartedAt.IsZero(), "no owner scan ran")
+		require.True(t, reply.Kinds[i].ScanEndedAt.IsZero(), "no owner scan ran")
+	}
+	require.Empty(t, reply.Items)
+	require.Empty(t, reply.Counts)
+}
@@ -0,0 +1,59 @@
+# ECS agent/scheduler bus contract, version 1
+
+This package owns the deployed wire vocabulary for the `ecs.bus.*`
+scheduler-to-agent boundary: subjects, payload JSON and the Layer-2 message
+types. It is a characterization of what is deployed today, not a redesign; it
+does not move the scheduler, the agent, or perform any NATS I/O itself.
+
+## Route table
+
+| Subject | Payload | Reply | Delivery | Queue group | Producer | Consumer |
+|---|---|---|---|---|---|---|
+| `ecs.bus.<account>.<cluster>.instance-register.<instanceId>` | `RegisterInstance` | none | fire-and-forget | none | none today | `spinifex_daemon` leader, `handlers/ecs/scheduler.go` `onRegister` |
+| `ecs.bus.<account>.<cluster>.instance-heartbeat.<instanceId>` | `Heartbeat` | none | fire-and-forget | none | none today | `spinifex_daemon` leader, `handlers/ecs/scheduler.go` `onHeartbeat` |
+| `ecs.bus.<account>.<cluster>.assign.<instanceId>` | `Assign` | none | fire-and-forget | none | none today | none today |
+| `ecs.bus.<account>.<cluster>.task-state.<taskId>` | `TaskState` | none | fire-and-forget | none | none today | `spinifex_daemon` leader, `handlers/ecs/scheduler.go` `onTaskState` |
+| `ecs.bus.<account>.<cluster>.service-reconcile` | none | none | fire-and-forget | none | `spinifex_daemon`, `handlers/ecs/instances.go` `SubmitTaskStateChange` | `spinifex_daemon` leader, `handlers/ecs/scheduler.go` `onReconcileWake` |
+
+The agent today registers, heartbeats and reports task state through the AWS
+gateway's `RegisterContainerInstance`, `PollAssignments` and
+`SubmitTaskStateChange` NATS actions instead of publishing on this bus; those
+actions are a separate, pre-existing subject family and carry some of the
+same message types (`Assign`, `TaskState`, `StopDirective`) as their wire
+body. Four of the five subject builders above, every route except
+`service-reconcile`, therefore have no current publisher. The scheduler still
+subscribes to all four wildcard patterns; only its election leader holds the
+subscriptions, which is why no queue group is needed. `service-reconcile` is
+the one route with a live producer and consumer: the worker that recorded a
+task-state change is rarely the leader, so it publishes a cross-node wake the
+leader's own subscription picks up.
+
+`StopDirective`, `ContainerStatus`, `InstanceCapacity`, `PortMapping`,
+`AssignContainer` and `SystemControl` are nested payload types carried inside
+`Assign` and `TaskState`; they travel on the same routes as their parent type
+and are not separately addressed.
+
+## Ownership
+
+The ECS domain owns the meaning of every subject and type in this package.
+The ecs-agent binary baked into the ECS node AMI is a deployed consumer: it
+decodes `Assign` and `StopDirective` and encodes `TaskState`, all carried
+today by the AWS-gateway actions that reuse these types.
+It does not encode `Heartbeat` or `RegisterInstance`.
+
+## Compatibility rules
+
+This is the deployed v1 contract. Changes follow N/N-1: a subject, JSON field
+name, JSON field type, or message semantics must not be renamed, retyped, or
+reinterpreted to mean something else. The AMI-baked agent cannot be upgraded
+in lockstep with the daemon, so it must keep decoding the shapes it already
+knows; `messages_test.go` pins the older agent's `AssignContainer` shape
+against the current one for exactly this reason. A breaking change needs a
+new, explicitly versioned successor package, not an edit here.
+
+## What this package does not do
+
+It does not move the scheduler, the agent, or any subscriber out of its
+current package, and it changes no ECS lifecycle behaviour: every subject
+string, JSON field and message type here is identical to the one the
+`handlers/ecs/bus` package declared before this move.
@@ -1,4 +1,4 @@
-package bus
+package ecsv1

 import "time"

@@ -13,9 +13,9 @@ type InstanceCapacity struct {
 	GPUIDs []string `json:"gpuIds,omitempty"`
 }

-// RegisterInstance is published on RegisterSubject when an ecs-agent boots and
-// joins its cluster. The scheduler records a container-instance entry keyed by
-// InstanceID (handlers_ecs.InstanceKey).
+// RegisterInstance is the registration payload the scheduler decodes from
+// RegisterSubject, which has no current publisher. It records a
+// container-instance entry keyed by InstanceID.
 type RegisterInstance struct {
 	AccountID    string           `json:"accountId"`
 	ClusterName  string           `json:"clusterName"`
@@ -27,9 +27,9 @@ type RegisterInstance struct {
 	RegisteredAt time.Time        `json:"registeredAt"`
 }

-// Heartbeat is published on HeartbeatSubject every ~30s while the agent is
-// healthy. A missed heartbeat past the scheduler's TTL marks the instance
-// DISCONNECTED (wired in Sprint 4e).
+// Heartbeat is the liveness payload the scheduler decodes from HeartbeatSubject,
+// which has no current publisher; the agent's registration action carries
+// liveness instead.
 type Heartbeat struct {
 	AccountID    string    `json:"accountId"`
 	ClusterName  string    `json:"clusterName"`
@@ -53,9 +53,9 @@ const (
 	TaskStatusStopped = "STOPPED"
 )

-// PortMapping is a container port exposed on the host (bridge mode v1). Shared
-// by the persisted ContainerDef and the AssignContainer wire payload below; Name
-// is a pure echo the agent does not read.
+// PortMapping is a container port exposed on the host (bridge mode v1), as
+// carried in the AssignContainer wire payload below; Name is a pure echo the
+// agent does not read.
 type PortMapping struct {
 	ContainerPort int    `json:"containerPort"`
 	HostPort      int    `json:"hostPort,omitempty"`
@@ -66,7 +66,6 @@ type PortMapping struct {
 }

 // SystemControl is a sysctl namespace/value pair (linux systemControls).
-// Shared by the persisted ContainerDef and the AssignContainer wire payload.
 type SystemControl struct {
 	Namespace string `json:"namespace"`
 	Value     string `json:"value"`
@@ -79,7 +78,7 @@ type AssignContainer struct {
 	CPU       int    `json:"cpu,omitempty"`
 	MemoryMiB int    `json:"memoryMiB,omitempty"`
 	// GPU is the whole-GPU count requested via resourceRequirements type=GPU.
-	// Device pinning/CDI injection is not wired yet (later Epic C tasks).
+	// Device pinning/CDI injection is not wired yet.
 	GPU          int               `json:"gpu,omitempty"`
 	Essential    bool              `json:"essential"`
 	Command      []string          `json:"command,omitempty"`
@@ -89,7 +88,7 @@ type AssignContainer struct {
 	// (host-side). Any other value means logs are discarded (warned at register).
 	LogDriver string `json:"logDriver,omitempty"`
 	// User, ReadonlyRootFilesystem, Privileged, PseudoTerminal, Interactive,
-	// SystemControls and CapAdd/CapDrop mirror the persisted ContainerDef and
+	// SystemControls and CapAdd/CapDrop mirror the persisted task definition and
 	// are applied to the OCI spec by the agent. Nil bools mean "not requested",
 	// distinct from an explicit false; an older agent decoding this struct
 	// ignores fields it does not know, so adding fields here is safe.
@@ -107,9 +106,9 @@ type AssignContainer struct {
 	StopTimeout  *int64 `json:"stopTimeout,omitempty"`
 }

-// Assign is published on AssignSubject when the scheduler places a task on this
-// instance (scheduler → agent). The agent pulls each container image, creates and
-// starts the containers via containerd, then reports progress on TaskStateSubject.
+// Assign places a task on an instance (scheduler → agent). It is the payload of
+// the gateway's PollAssignments action; AssignSubject carries nothing today.
+// The agent pulls each image, starts the containers, then reports TaskState.
 type Assign struct {
 	AccountID       string            `json:"accountId"`
 	ClusterName     string            `json:"clusterName"`
@@ -158,9 +157,9 @@ type ContainerStatus struct {
 	GPUIDs []string `json:"gpuIds,omitempty"`
 }

-// TaskState is published on TaskStateSubject as the agent drives a task through
-// its lifecycle (agent → scheduler). The scheduler updates the task record and
-// recomputes the instance's remaining capacity.
+// TaskState reports a task's lifecycle (agent → scheduler). It is the payload of
+// the gateway's SubmitTaskStateChange action; TaskStateSubject carries nothing
+// today. The scheduler updates the task record and the instance's capacity.
 type TaskState struct {
 	AccountID   string            `json:"accountId"`
 	ClusterName string            `json:"clusterName"`
@@ -0,0 +1,193 @@
+package ecsv1_test
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+
+	ecsv1 "github.com/mulgadc/spinifex/contracts/ecs/v1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+var pinTime = time.Date(2026, 1, 15, 10, 30, 0, 0, time.UTC)
+
+func TestRegisterInstance_JSON(t *testing.T) {
+	golden := `{"accountId":"123456789012","clusterName":"default","instanceId":"i-abc123",` +
+		`"availabilityZone":"az-1","hostname":"host-1",` +
+		`"capacity":{"cpu":2048,"memoryMiB":4096},"agentVersion":"1.0.0",` +
+		`"registeredAt":"2026-01-15T10:30:00Z"}`
+	msg := ecsv1.RegisterInstance{
+		AccountID: "123456789012", ClusterName: "default", InstanceID: "i-abc123",
+		AZ: "az-1", Hostname: "host-1",
+		Capacity:     ecsv1.InstanceCapacity{CPU: 2048, MemoryMiB: 4096},
+		AgentVersion: "1.0.0", RegisteredAt: pinTime,
+	}
+
+	data, err := json.Marshal(msg)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(data))
+
+	var decoded ecsv1.RegisterInstance
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, msg, decoded)
+}
+
+func TestInstanceCapacity_GPUFields(t *testing.T) {
+	golden := `{"cpu":4096,"memoryMiB":8192,"gpu":2,"gpuIds":["GPU-1","GPU-2"]}`
+	capacity := ecsv1.InstanceCapacity{CPU: 4096, MemoryMiB: 8192, GPU: 2, GPUIDs: []string{"GPU-1", "GPU-2"}}
+
+	data, err := json.Marshal(capacity)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(data))
+
+	var decoded ecsv1.InstanceCapacity
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, capacity, decoded)
+}
+
+func TestHeartbeat_JSON(t *testing.T) {
+	golden := `{"accountId":"123456789012","clusterName":"default","instanceId":"i-abc123",` +
+		`"status":"ACTIVE","runningTasks":3,"sentAt":"2026-01-15T10:30:00Z"}`
+	msg := ecsv1.Heartbeat{
+		AccountID: "123456789012", ClusterName: "default", InstanceID: "i-abc123",
+		Status: ecsv1.StatusActive, RunningTasks: 3, SentAt: pinTime,
+	}
+
+	data, err := json.Marshal(msg)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(data))
+
+	var decoded ecsv1.Heartbeat
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, msg, decoded)
+}
+
+func TestStopDirective_JSON(t *testing.T) {
+	golden := `{"taskId":"t-deadbeef","reason":"drain"}`
+	msg := ecsv1.StopDirective{TaskID: "t-deadbeef", Reason: "drain"}
+
+	data, err := json.Marshal(msg)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(data))
+
+	var decoded ecsv1.StopDirective
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, msg, decoded)
+}
+
+func TestStopDirective_OmitsEmptyReason(t *testing.T) {
+	data, err := json.Marshal(ecsv1.StopDirective{TaskID: "t-deadbeef"})
+	require.NoError(t, err)
+	assert.JSONEq(t, `{"taskId":"t-deadbeef"}`, string(data))
+}
+
+func TestAssign_JSON(t *testing.T) {
+	ro := true
+	start := int64(30)
+	golden := `{"accountId":"123456789012","clusterName":"default","instanceId":"i-abc123",` +
+		`"taskId":"t-deadbeef","taskArn":"arn:aws:ecs:ap-southeast-2:123456789012:task/default/t-deadbeef",` +
+		`"taskDefFamily":"web","taskDefRevision":2,` +
+		`"containers":[{"name":"app","image":"registry/app:1","essential":true,` +
+		`"readonlyRootFilesystem":true,"startTimeout":30}],` +
+		`"eniId":"eni-1","eniMac":"02:00:00:00:00:01","eniPrivateIp":"10.0.1.5","eniSubnetId":"subnet-1",` +
+		`"credId":"c-1","taskRoleArn":"arn:aws:iam::123456789012:role/task",` +
+		`"executionRoleArn":"arn:aws:iam::123456789012:role/exec",` +
+		`"assignedAt":"2026-01-15T10:30:00Z"}`
+	msg := ecsv1.Assign{
+		AccountID: "123456789012", ClusterName: "default", InstanceID: "i-abc123",
+		TaskID: "t-deadbeef", TaskARN: "arn:aws:ecs:ap-southeast-2:123456789012:task/default/t-deadbeef",
+		TaskDefFamily: "web", TaskDefRevision: 2,
+		Containers: []ecsv1.AssignContainer{{
+			Name: "app", Image: "registry/app:1", Essential: true,
+			ReadonlyRootFilesystem: &ro, StartTimeout: &start,
+		}},
+		ENIID: "eni-1", ENIMacAddress: "02:00:00:00:00:01", ENIPrivateIP: "10.0.1.5", ENISubnetID: "subnet-1",
+		CredID: "c-1", TaskRoleARN: "arn:aws:iam::123456789012:role/task",
+		ExecutionRoleARN: "arn:aws:iam::123456789012:role/exec",
+		AssignedAt:       pinTime,
+	}
+
+	data, err := json.Marshal(msg)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(data))
+
+	var decoded ecsv1.Assign
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, msg, decoded)
+}
+
+func TestAssignContainer_FullFields(t *testing.T) {
+	ro, priv, pty, interactive := true, true, false, true
+	start, stop := int64(30), int64(10)
+	golden := `{"name":"app","image":"registry/app:1","cpu":256,"memoryMiB":512,"gpu":1,` +
+		`"essential":true,"command":["/bin/app"],"environment":{"ENV":"prod"},` +
+		`"portMappings":[{"containerPort":80,"hostPort":8080,"protocol":"tcp","name":"http"}],` +
+		`"logDriver":"json-file","user":"1000","readonlyRootFilesystem":true,"privileged":true,` +
+		`"pseudoTerminal":false,"interactive":true,` +
+		`"systemControls":[{"namespace":"net.core.somaxconn","value":"1024"}],` +
+		`"capAdd":["SYS_PTRACE"],"capDrop":["NET_RAW"],"startTimeout":30,"stopTimeout":10}`
+	msg := ecsv1.AssignContainer{
+		Name: "app", Image: "registry/app:1", CPU: 256, MemoryMiB: 512, GPU: 1,
+		Essential: true, Command: []string{"/bin/app"}, Environment: map[string]string{"ENV": "prod"},
+		PortMappings:           []ecsv1.PortMapping{{ContainerPort: 80, HostPort: 8080, Protocol: "tcp", Name: "http"}},
+		LogDriver:              "json-file",
+		User:                   "1000",
+		ReadonlyRootFilesystem: &ro,
+		Privileged:             &priv,
+		PseudoTerminal:         &pty,
+		Interactive:            &interactive,
+		SystemControls:         []ecsv1.SystemControl{{Namespace: "net.core.somaxconn", Value: "1024"}},
+		CapAdd:                 []string{"SYS_PTRACE"},
+		CapDrop:                []string{"NET_RAW"},
+		StartTimeout:           &start,
+		StopTimeout:            &stop,
+	}
+
+	data, err := json.Marshal(msg)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(data))
+
+	var decoded ecsv1.AssignContainer
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, msg, decoded)
+}
+
+func TestAssignContainer_OmitsEmptyFields(t *testing.T) {
+	data, err := json.Marshal(ecsv1.AssignContainer{Name: "app", Image: "registry/app:1"})
+	require.NoError(t, err)
+	assert.JSONEq(t, `{"name":"app","image":"registry/app:1","essential":false}`, string(data))
+}
+
+func TestTaskState_JSON(t *testing.T) {
+	exit := 0
+	golden := `{"accountId":"123456789012","clusterName":"default","instanceId":"i-abc123",` +
+		`"taskId":"t-deadbeef","lastStatus":"STOPPED",` +
+		`"containers":[{"name":"app","status":"STOPPED","containerId":"c-1","exitCode":0,"gpuIds":["GPU-1"]}],` +
+		`"reason":"done","reportedAt":"2026-01-15T10:30:00Z"}`
+	msg := ecsv1.TaskState{
+		AccountID: "123456789012", ClusterName: "default", InstanceID: "i-abc123",
+		TaskID: "t-deadbeef", LastStatus: ecsv1.TaskStatusStopped,
+		Containers: []ecsv1.ContainerStatus{{
+			Name: "app", Status: ecsv1.TaskStatusStopped, ContainerID: "c-1",
+			ExitCode: &exit, GPUIDs: []string{"GPU-1"},
+		}},
+		Reason: "done", ReportedAt: pinTime,
+	}
+
+	data, err := json.Marshal(msg)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(data))
+
+	var decoded ecsv1.TaskState
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, msg, decoded)
+}
+
+func TestLifecycleStatusConstants(t *testing.T) {
+	assert.Equal(t, "ACTIVE", ecsv1.StatusActive)
+	assert.Equal(t, "DRAINING", ecsv1.StatusDraining)
+	assert.Equal(t, "PENDING", ecsv1.TaskStatusPending)
+	assert.Equal(t, "RUNNING", ecsv1.TaskStatusRunning)
+	assert.Equal(t, "STOPPED", ecsv1.TaskStatusStopped)
+}
@@ -1,26 +1,26 @@
-package bus_test
+package ecsv1_test

 import (
 	"encoding/json"
 	"testing"

-	"github.com/mulgadc/spinifex/spinifex/handlers/ecs/bus"
+	ecsv1 "github.com/mulgadc/spinifex/contracts/ecs/v1"
 )

 // oldAssignContainer models an ecs-agent built before the container-runtime
 // fields were added: the wire shape AssignContainer had before user,
 // readonlyRootFilesystem, privileged and the rest. The AMI-baked decode side.
 type oldAssignContainer struct {
-	Name         string            `json:"name"`
-	Image        string            `json:"image"`
-	CPU          int               `json:"cpu,omitempty"`
-	MemoryMiB    int               `json:"memoryMiB,omitempty"`
-	GPU          int               `json:"gpu,omitempty"`
-	Essential    bool              `json:"essential"`
-	Command      []string          `json:"command,omitempty"`
-	Environment  map[string]string `json:"environment,omitempty"`
-	PortMappings []bus.PortMapping `json:"portMappings,omitempty"`
-	LogDriver    string            `json:"logDriver,omitempty"`
+	Name         string              `json:"name"`
+	Image        string              `json:"image"`
+	CPU          int                 `json:"cpu,omitempty"`
+	MemoryMiB    int                 `json:"memoryMiB,omitempty"`
+	GPU          int                 `json:"gpu,omitempty"`
+	Essential    bool                `json:"essential"`
+	Command      []string            `json:"command,omitempty"`
+	Environment  map[string]string   `json:"environment,omitempty"`
+	PortMappings []ecsv1.PortMapping `json:"portMappings,omitempty"`
+	LogDriver    string              `json:"logDriver,omitempty"`
 }

 // An agent baked into the ECS AMI must survive a daemon upgrade that adds
@@ -30,12 +30,12 @@ func TestAssignContainer_OlderAgentIgnoresUnknownFields(t *testing.T) {
 	ro := true
 	priv := true
 	start := int64(30)
-	current := bus.AssignContainer{
+	current := ecsv1.AssignContainer{
 		Name: "app", Image: "registry/app:1", Essential: true,
 		User:                   "1000",
 		ReadonlyRootFilesystem: &ro,
 		Privileged:             &priv,
-		SystemControls:         []bus.SystemControl{{Namespace: "net.core.somaxconn", Value: "1024"}},
+		SystemControls:         []ecsv1.SystemControl{{Namespace: "net.core.somaxconn", Value: "1024"}},
 		CapAdd:                 []string{"SYS_PTRACE"},
 		StartTimeout:           &start,
 	}
@@ -1,12 +1,10 @@
-// Package bus defines the Layer-2 internal scheduler↔agent NATS subjects and
-// wire payloads for the ECS control plane (ecs-v1.md Q14). Both the ecs-agent
-// (publisher) and the spinifex scheduler (subscriber, Sprint 4e) import it so the
-// subject shape and message schema have a single source of truth.
+// Package ecsv1 defines version 1 of the ECS scheduler-agent NATS subjects and
+// wire payloads. The ecs-agent and the spinifex scheduler both consume this
+// shared vocabulary; the README's route table records which routes are live.
 //
 // Cluster identity is "<accountID>.<clusterName>" (matching the KV layout), not a
-// UUID. The per-AZ NATS routing inserts "{azID}" after "ecs." — keep
-// these builders the one place that knows the shape so that change stays local.
-package bus
+// UUID; these builders are the one place that knows the subject shape.
+package ecsv1

 import "fmt"

@@ -15,24 +13,27 @@ func Prefix(accountID, clusterName string) string {
 	return fmt.Sprintf("ecs.bus.%s.%s", accountID, clusterName)
 }

-// RegisterSubject is published by the agent at boot (agent → scheduler).
+// RegisterSubject is the per-instance registration subject (agent → scheduler).
+// The scheduler subscribes to it; nothing publishes on it today.
 func RegisterSubject(accountID, clusterName, instanceID string) string {
 	return fmt.Sprintf("%s.instance-register.%s", Prefix(accountID, clusterName), instanceID)
 }

-// HeartbeatSubject is published by the agent every 30s (agent → scheduler).
+// HeartbeatSubject is the per-instance liveness subject (agent → scheduler).
+// The scheduler subscribes to it; nothing publishes on it today.
 func HeartbeatSubject(accountID, clusterName, instanceID string) string {
 	return fmt.Sprintf("%s.instance-heartbeat.%s", Prefix(accountID, clusterName), instanceID)
 }

 // AssignSubject is the per-instance task-assignment subject (scheduler → agent).
-// The agent does not subscribe to it until Sprint 4e.
+// No production code subscribes to it today; assignments are delivered through
+// the AWS-API gateway poll path instead.
 func AssignSubject(accountID, clusterName, instanceID string) string {
 	return fmt.Sprintf("%s.assign.%s", Prefix(accountID, clusterName), instanceID)
 }

-// TaskStateSubject is the per-task state-report subject (agent → scheduler),
-// published from Sprint 4e.
+// TaskStateSubject is the per-task state-report subject (agent → scheduler).
+// The scheduler subscribes to it; nothing publishes on it today.
 func TaskStateSubject(accountID, clusterName, taskID string) string {
 	return fmt.Sprintf("%s.task-state.%s", Prefix(accountID, clusterName), taskID)
 }
@@ -1,4 +1,4 @@
-package bus
+package ecsv1

 import "testing"

@@ -0,0 +1,17 @@
+# EKS v1 contracts
+
+This package owns the deployed EKS add-on contract between the control-plane guest (the on-VM addon-sync agent, `eks-gateway-fetch` and `eks-gateway-publish`) and the host (the AWS gateway and the cluster reconciler). It is not an AWS tenant-facing API.
+
+## Delivery report
+
+`AddonStatusSubject` retains the deployed `eks.addon.<account>.<cluster>.status` route. The guest's `mulga-eks-addon-sync.sh` builds an `AddonStatusReport` with `printf`, so it always sends `message` (possibly empty); the gateway relays the payload verbatim on the `addon` channel of `internal-publish`. `AddonDeliveryPhase` is the closed set `applied`, `ready`, `failed`.
+
+## Staged manifests
+
+`InternalAddonsResponse` is the body of `GET /clusters/{name}/internal-addons/{account}`. The gateway renders it with the AWS SDK REST-JSON marshaller (`jsonutil.BuildJSON`), which ignores `json` tags, so the deployed body uses Go field names and always includes empty strings, for example `{"Addons":[{"AddonName":"x","AddonVersion":"1","ServiceAccountRoleArn":"","ConfigurationValues":""}]}`. The guest decodes it with `encoding/json`, which matches keys case-insensitively, then emits it as tab-separated lines for the shell agent.
+
+The `json` tags on `StagedAddonManifest` are the host-internal NATS form used between the gateway and the daemon (`eks.ListStagedAddonManifests`). They do not describe the guest-facing body.
+
+## Compatibility boundary
+
+The subject, phase values, both JSON forms and Go field names are wire compatibility; `addon_status_test.go` and `addon_manifest_test.go` pin them with literal bytes. A generation-aware or otherwise incompatible delivery protocol needs a successor version; it is not a v1 change.
@@ -0,0 +1,18 @@
+package eksv1
+
+// StagedAddonManifest describes one add-on staged for delivery: the bundled
+// add-on and version plus the operator config the guest renders it with. The
+// json tags are the host-internal NATS form; see InternalAddonsResponse.
+type StagedAddonManifest struct {
+	AddonName             string `json:"addonName"`
+	AddonVersion          string `json:"addonVersion"`
+	ServiceAccountRoleArn string `json:"serviceAccountRoleArn,omitempty"`
+	ConfigurationValues   string `json:"configurationValues,omitempty"`
+}
+
+// InternalAddonsResponse is the internal-addons HTTP body. The gateway's SDK
+// REST-JSON marshaller ignores json tags, so Go field names (and order) are the
+// deployed bytes; the guest decodes them case-insensitively with encoding/json.
+type InternalAddonsResponse struct {
+	Addons []StagedAddonManifest `json:"addons"`
+}
@@ -0,0 +1,77 @@
+package eksv1
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/aws/aws-sdk-go/private/protocol/json/jsonutil"
+	"github.com/stretchr/testify/require"
+)
+
+var testManifests = []StagedAddonManifest{
+	{
+		AddonName:             "aws-load-balancer-controller",
+		AddonVersion:          "2.11.0",
+		ServiceAccountRoleArn: "arn:aws:iam::123456789012:role/alb",
+		ConfigurationValues:   `{"replicaCount":2}`,
+	},
+	{AddonName: "spinifex-noop", AddonVersion: "0.1.0"},
+}
+
+// The host-internal NATS form: camelCase tags, empty optionals omitted.
+func TestStagedAddonManifestJSONContract(t *testing.T) {
+	data, err := json.Marshal(testManifests)
+	require.NoError(t, err)
+	require.Equal(t, `[`+
+		`{"addonName":"aws-load-balancer-controller","addonVersion":"2.11.0",`+
+		`"serviceAccountRoleArn":"arn:aws:iam::123456789012:role/alb","configurationValues":"{\"replicaCount\":2}"},`+
+		`{"addonName":"spinifex-noop","addonVersion":"0.1.0"}]`,
+		string(data))
+}
+
+// The deployed guest body, as rendered by the gateway's SDK REST-JSON
+// marshaller: Go field names in declaration order, empty strings present.
+func TestInternalAddonsResponse_RESTJSONBody(t *testing.T) {
+	data, err := jsonutil.BuildJSON(&InternalAddonsResponse{Addons: testManifests})
+	require.NoError(t, err)
+	require.Equal(t, `{"Addons":[`+
+		`{"AddonName":"aws-load-balancer-controller","AddonVersion":"2.11.0",`+
+		`"ServiceAccountRoleArn":"arn:aws:iam::123456789012:role/alb","ConfigurationValues":"{\"replicaCount\":2}"},`+
+		`{"AddonName":"spinifex-noop","AddonVersion":"0.1.0","ServiceAccountRoleArn":"","ConfigurationValues":""}]}`,
+		string(data))
+
+	empty, err := jsonutil.BuildJSON(&InternalAddonsResponse{Addons: []StagedAddonManifest{}})
+	require.NoError(t, err)
+	require.Equal(t, `{"Addons":[]}`, string(empty))
+}
+
+// The tag form encoding/json would emit; not what the gateway sends, but the
+// guest must decode both this and the REST-JSON body identically.
+func TestInternalAddonsResponse_EncodingJSONForm(t *testing.T) {
+	data, err := json.Marshal(InternalAddonsResponse{Addons: testManifests})
+	require.NoError(t, err)
+	require.Equal(t, `{"addons":[`+
+		`{"addonName":"aws-load-balancer-controller","addonVersion":"2.11.0",`+
+		`"serviceAccountRoleArn":"arn:aws:iam::123456789012:role/alb","configurationValues":"{\"replicaCount\":2}"},`+
+		`{"addonName":"spinifex-noop","addonVersion":"0.1.0"}]}`,
+		string(data))
+}
+
+func TestInternalAddonsResponse_DecodesBothForms(t *testing.T) {
+	for name, body := range map[string]string{
+		"rest-json": `{"Addons":[` +
+			`{"AddonName":"aws-load-balancer-controller","AddonVersion":"2.11.0",` +
+			`"ServiceAccountRoleArn":"arn:aws:iam::123456789012:role/alb","ConfigurationValues":"{\"replicaCount\":2}"},` +
+			`{"AddonName":"spinifex-noop","AddonVersion":"0.1.0","ServiceAccountRoleArn":"","ConfigurationValues":""}]}`,
+		"encoding-json": `{"addons":[` +
+			`{"addonName":"aws-load-balancer-controller","addonVersion":"2.11.0",` +
+			`"serviceAccountRoleArn":"arn:aws:iam::123456789012:role/alb","configurationValues":"{\"replicaCount\":2}"},` +
+			`{"addonName":"spinifex-noop","addonVersion":"0.1.0"}]}`,
+	} {
+		t.Run(name, func(t *testing.T) {
+			var got InternalAddonsResponse
+			require.NoError(t, json.Unmarshal([]byte(body), &got))
+			require.Equal(t, InternalAddonsResponse{Addons: testManifests}, got)
+		})
+	}
+}
@@ -0,0 +1,37 @@
+// Package eksv1 defines version 1 of the EKS add-on contract between the
+// control-plane guest and the host. v1 is the deployed guest contract; a
+// generation-aware delivery protocol needs a successor version, not a v1 edit.
+package eksv1
+
+import "fmt"
+
+// AddonStatusSubject returns the per-cluster NATS subject that carries every
+// add-on delivery report: "eks.addon.{accountID}.{clusterName}.status".
+func AddonStatusSubject(accountID, clusterName string) string {
+	return fmt.Sprintf("eks.addon.%s.%s.status", accountID, clusterName)
+}
+
+// AddonDeliveryPhase is the guest-observed delivery phase of one add-on. The
+// host-side add-on owner maps it onto the AWS-visible add-on status.
+type AddonDeliveryPhase string
+
+const (
+	// AddonPhaseApplied: the rendered manifest is in the K3s auto-deploy dir
+	// but its workloads are not yet Ready.
+	AddonPhaseApplied AddonDeliveryPhase = "applied"
+	// AddonPhaseReady: the add-on's workloads rolled out successfully.
+	AddonPhaseReady AddonDeliveryPhase = "ready"
+	// AddonPhaseFailed: render or rollout failed.
+	AddonPhaseFailed AddonDeliveryPhase = "failed"
+)
+
+// AddonStatusReport is the add-on delivery report payload. The guest builds it
+// by hand (always sending "message", even empty) and the gateway relays it
+// verbatim onto AddonStatusSubject. TS is the publish time in unix seconds.
+type AddonStatusReport struct {
+	Addon   string             `json:"addon"`
+	Version string             `json:"version"`
+	Phase   AddonDeliveryPhase `json:"phase"`
+	Message string             `json:"message,omitempty"`
+	TS      int64              `json:"ts"`
+}
@@ -0,0 +1,66 @@
+package eksv1
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestAddonStatusSubject(t *testing.T) {
+	require.Equal(t, "eks.addon.111122223333.prod.status", AddonStatusSubject("111122223333", "prod"))
+}
+
+func TestAddonStatusReportJSONContract(t *testing.T) {
+	for _, tc := range []struct {
+		report AddonStatusReport
+		want   string
+	}{
+		{
+			report: AddonStatusReport{Addon: "coredns", Version: "1.11.3", Phase: AddonPhaseApplied, TS: 1736935200},
+			want:   `{"addon":"coredns","version":"1.11.3","phase":"applied","ts":1736935200}`,
+		},
+		{
+			report: AddonStatusReport{Addon: "coredns", Version: "1.11.3", Phase: AddonPhaseReady, TS: 1736935200},
+			want:   `{"addon":"coredns","version":"1.11.3","phase":"ready","ts":1736935200}`,
+		},
+		{
+			report: AddonStatusReport{Addon: "coredns", Version: "1.11.3", Phase: AddonPhaseFailed, Message: "rollout stalled", TS: 1736935200},
+			want:   `{"addon":"coredns","version":"1.11.3","phase":"failed","message":"rollout stalled","ts":1736935200}`,
+		},
+	} {
+		t.Run(tc.want, func(t *testing.T) {
+			data, err := json.Marshal(tc.report)
+			require.NoError(t, err)
+			require.Equal(t, tc.want, string(data))
+		})
+	}
+}
+
+// mulga-eks-addon-sync.sh builds the report with printf and always sends
+// "message", empty when there is nothing to say.
+func TestAddonStatusReport_DecodesGuestPrintfForm(t *testing.T) {
+	for _, tc := range []struct {
+		body string
+		want AddonStatusReport
+	}{
+		{
+			body: `{"addon":"aws-load-balancer-controller","version":"2.11.0","phase":"applied","message":"","ts":1736935200}`,
+			want: AddonStatusReport{Addon: "aws-load-balancer-controller", Version: "2.11.0", Phase: AddonPhaseApplied, TS: 1736935200},
+		},
+		{
+			body: `{"addon":"aws-load-balancer-controller","version":"2.11.0","phase":"ready","message":"","ts":1736935200}`,
+			want: AddonStatusReport{Addon: "aws-load-balancer-controller", Version: "2.11.0", Phase: AddonPhaseReady, TS: 1736935200},
+		},
+		{
+			body: `{"addon":"aws-load-balancer-controller","version":"9.9.9","phase":"failed","message":"no baked bundle for version 9.9.9","ts":1736935200}`,
+			want: AddonStatusReport{Addon: "aws-load-balancer-controller", Version: "9.9.9", Phase: AddonPhaseFailed, Message: "no baked bundle for version 9.9.9", TS: 1736935200},
+		},
+	} {
+		t.Run(string(tc.want.Phase), func(t *testing.T) {
+			var got AddonStatusReport
+			require.NoError(t, json.Unmarshal([]byte(tc.body), &got))
+			require.Equal(t, tc.want, got)
+		})
+	}
+}
@@ -0,0 +1,34 @@
+package eksv1
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// A v1 decoder ignores fields a later sender adds, so a report carrying them
+// decodes to the same value as one without.
+func TestAddonStatusReport_IgnoresUnknownFields(t *testing.T) {
+	body := `{"addon":"argocd","version":"3.0.23","phase":"ready","message":"","ts":1736935200,` +
+		`"incarnationId":"inc-1","generation":4,"executorEpoch":7}`
+	var got AddonStatusReport
+	require.NoError(t, json.Unmarshal([]byte(body), &got))
+	require.Equal(t, AddonStatusReport{Addon: "argocd", Version: "3.0.23", Phase: AddonPhaseReady, TS: 1736935200}, got)
+}
+
+// Both deployed body forms tolerate added top-level and per-add-on fields.
+func TestInternalAddonsResponse_IgnoresUnknownFields(t *testing.T) {
+	for name, body := range map[string]string{
+		"rest-json": `{"Addons":[{"AddonName":"spinifex-noop","AddonVersion":"0.1.0","ServiceAccountRoleArn":"",` +
+			`"ConfigurationValues":"","IncarnationId":"inc-1","Generation":4}],"ExecutorEpoch":7}`,
+		"encoding-json": `{"addons":[{"addonName":"spinifex-noop","addonVersion":"0.1.0",` +
+			`"incarnationId":"inc-1","generation":4}],"executorEpoch":7}`,
+	} {
+		t.Run(name, func(t *testing.T) {
+			var got InternalAddonsResponse
+			require.NoError(t, json.Unmarshal([]byte(body), &got))
+			require.Equal(t, InternalAddonsResponse{Addons: []StagedAddonManifest{{AddonName: "spinifex-noop", AddonVersion: "0.1.0"}}}, got)
+		})
+	}
+}
@@ -0,0 +1,68 @@
+# Network realisation contract, version 1
+
+This package owns the deployed wire vocabulary for the `vpc.*`
+control-plane-to-network-realisation boundary: subjects, payload JSON, the
+`{success,error}` acknowledgement envelope, delivery mode and the
+`vpcd-workers` queue group. It does not move `vpcd`, perform any NATS I/O, or
+change any lifecycle or reliability semantics. It is a characterization of
+what is deployed today, split one route family per file, not a redesign.
+
+## Ownership
+
+Network owns the meaning and wire contract of every route below, because it
+owns OVN and host realisation. EC2 and the other managed-service domains own
+their own AWS-visible state transitions and decide when, and whether, to
+issue a projection onto one of these subjects; this package does not grant
+them authority over a route's semantics, only a stable shape to publish
+against.
+
+## Route table
+
+| Subject | Payload | Reply | Delivery | Queue group |
+|---|---|---|---|---|
+| `vpc.create` | `VPCEvent` | none | fire-and-forget | `vpcd-workers` |
+| `vpc.delete` | `VPCEvent` | none | fire-and-forget | `vpcd-workers` |
+| `vpc.create-subnet` | `SubnetEvent` | none | fire-and-forget | `vpcd-workers` |
+| `vpc.delete-subnet` | `SubnetEvent` | none | fire-and-forget | `vpcd-workers` |
+| `vpc.create-port` | `PortEvent` | `AckEnvelope` | request/reply, 5s | `vpcd-workers` |
+| `vpc.delete-port` | `PortEvent` | `AckEnvelope` | request/reply, 5s; caller treats failure as non-fatal | `vpcd-workers` |
+| `vpc.update-port-sgs` | `PortSecurityGroupsUpdateEvent` | `AckEnvelope` | request/reply, 5s | `vpcd-workers` |
+| `vpc.igw-attach` | `InternetGatewayEvent` | none | fire-and-forget, non-fatal | `vpcd-workers` |
+| `vpc.igw-detach` | `InternetGatewayEvent` | none | fire-and-forget, non-fatal | `vpcd-workers` |
+| `vpc.add-nat` | `NATEvent` | `AckEnvelope` | request/reply, 45s (OVN flows barrier); some callers fire-and-forget | `vpcd-workers` |
+| `vpc.delete-nat` | `NATEvent` | `AckEnvelope` | request/reply, 15s, retried on `ErrNoResponders` (3 attempts, 500ms apart) | `vpcd-workers` |
+| `vpc.add-nat-gateway` | `NATGatewayEvent` | none | fire-and-forget | `vpcd-workers` |
+| `vpc.delete-nat-gateway` | `NATGatewayEvent` | none | fire-and-forget | `vpcd-workers` |
+| `vpc.add-igw-route` | `IGWRouteEvent` | none | fire-and-forget | `vpcd-workers` |
+| `vpc.delete-igw-route` | `IGWRouteEvent` | none | fire-and-forget | `vpcd-workers` |
+| `vpc.gate-subnet-egress` | `SubnetEgressGateEvent` | none | fire-and-forget | `vpcd-workers` |
+| `vpc.ungate-subnet-egress` | `SubnetEgressUngateEvent` | none | fire-and-forget | `vpcd-workers` |
+| `vpc.add-system-egress` | `SystemEgressEvent` | none | fire-and-forget | `vpcd-workers` |
+| `vpc.delete-system-egress` | `SystemEgressEvent` | none | fire-and-forget | `vpcd-workers` |
+| `vpc.create-sg` | `SecurityGroupEvent` | `AckEnvelope` | request/reply, 5s | `vpcd-workers` |
+| `vpc.delete-sg` | `SecurityGroupEvent` | `AckEnvelope` | request/reply, 5s, idempotent | `vpcd-workers` |
+| `vpc.update-sg` | `SecurityGroupEvent` | `AckEnvelope` | request/reply, 5s | `vpcd-workers` |
+
+Producer for every route above is the daemon (`spinifex-daemon`), through the
+typed client in `domains/network/projection`; `vpc.add-system-egress` has no
+current producer.
+Consumer for every route is `vpcd`, by way of `domains/network/subscribers`.
+This package is the sole declared owner of every subject and type above,
+including `vpc.igw-attach`/`vpc.igw-detach`, which were previously also
+declared in `contracts/ec2/v1`; that duplicate has been removed.
+
+## Compatibility rules
+
+This is the deployed v1 contract. Changes follow N/N-1: a subject, JSON field
+name, JSON field type, or the ack envelope shape must not be renamed,
+retyped, or reinterpreted to mean something else. A breaking change needs a
+new, explicitly versioned successor package, not an edit here. Every subject
+and golden JSON literal in this package is pinned by an external `_test`
+package; a failing pin means the change broke compatibility, not that the
+test is stale.
+
+## What this package does not do
+
+It does not move `vpcd` or any subscriber out of its current package. It does
+not change any route's delivery mode, timeout, retry budget, queue group, or
+the NAT add barrier.
@@ -0,0 +1,9 @@
+package networkv1
+
+// AckEnvelope is the reply body on every request/reply route in this
+// package: Success true with no error, or Success false with Error set.
+// Fire-and-forget routes never populate it; there is no reply subject.
+type AckEnvelope struct {
+	Success bool   `json:"success"`
+	Error   string `json:"error,omitempty"`
+}
@@ -0,0 +1,41 @@
+package networkv1_test
+
+import (
+	"encoding/json"
+	"testing"
+
+	networkv1 "github.com/mulgadc/spinifex/contracts/network/v1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestAckEnvelope_JSON pins both ack envelope shapes: bare success, and
+// failure with its error populated. Error is omitempty, so the two must
+// not be mistaken for the same shape.
+func TestAckEnvelope_JSON(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		golden := `{"success":true}`
+		env := networkv1.AckEnvelope{Success: true}
+
+		marshaled, err := json.Marshal(env)
+		require.NoError(t, err)
+		assert.JSONEq(t, golden, string(marshaled))
+
+		var decoded networkv1.AckEnvelope
+		require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+		assert.Equal(t, env, decoded)
+	})
+
+	t.Run("error", func(t *testing.T) {
+		golden := `{"success":false,"error":"boom"}`
+		env := networkv1.AckEnvelope{Success: false, Error: "boom"}
+
+		marshaled, err := json.Marshal(env)
+		require.NoError(t, err)
+		assert.JSONEq(t, golden, string(marshaled))
+
+		var decoded networkv1.AckEnvelope
+		require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+		assert.Equal(t, env, decoded)
+	})
+}
@@ -0,0 +1,20 @@
+package networkv1
+
+const (
+	// IGWRouteAddSubject asks vpcd to install the per-subnet egress policy
+	// for a route-table route to an internet gateway. Fire-and-forget.
+	IGWRouteAddSubject = "vpc.add-igw-route"
+
+	// IGWRouteDeleteSubject asks vpcd to remove that egress policy.
+	// Fire-and-forget.
+	IGWRouteDeleteSubject = "vpc.delete-igw-route"
+)
+
+// IGWRouteEvent is the payload on IGWRouteAddSubject and
+// IGWRouteDeleteSubject.
+type IGWRouteEvent struct {
+	VpcId             string `json:"vpc_id"`
+	SubnetId          string `json:"subnet_id"`
+	DestinationCidr   string `json:"destination_cidr"`
+	InternetGatewayId string `json:"internet_gateway_id"`
+}
@@ -0,0 +1,30 @@
+package networkv1_test
+
+import (
+	"encoding/json"
+	"testing"
+
+	networkv1 "github.com/mulgadc/spinifex/contracts/network/v1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestIGWRouteSubjects(t *testing.T) {
+	assert.Equal(t, "vpc.add-igw-route", networkv1.IGWRouteAddSubject)
+	assert.Equal(t, "vpc.delete-igw-route", networkv1.IGWRouteDeleteSubject)
+}
+
+func TestIGWRouteEvent_JSON(t *testing.T) {
+	golden := `{"vpc_id":"vpc-1","subnet_id":"subnet-1","destination_cidr":"0.0.0.0/0","internet_gateway_id":"igw-1"}`
+	evt := networkv1.IGWRouteEvent{
+		VpcId: "vpc-1", SubnetId: "subnet-1", DestinationCidr: "0.0.0.0/0", InternetGatewayId: "igw-1",
+	}
+
+	marshaled, err := json.Marshal(evt)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(marshaled))
+
+	var decoded networkv1.IGWRouteEvent
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, evt, decoded)
+}
@@ -0,0 +1,18 @@
+package networkv1
+
+const (
+	// InternetGatewayAttachSubject asks vpcd to build the OVN external
+	// switch, gateway and SNAT. Fire-and-forget, non-fatal on failure.
+	InternetGatewayAttachSubject = "vpc.igw-attach"
+
+	// InternetGatewayDetachSubject asks vpcd to tear down the OVN external
+	// switch, gateway and NAT. Fire-and-forget, non-fatal on failure.
+	InternetGatewayDetachSubject = "vpc.igw-detach"
+)
+
+// InternetGatewayEvent is the payload on InternetGatewayAttachSubject and
+// InternetGatewayDetachSubject.
+type InternetGatewayEvent struct {
+	InternetGatewayId string `json:"internet_gateway_id"`
+	VpcId             string `json:"vpc_id"`
+}
@@ -0,0 +1,28 @@
+package networkv1_test
+
+import (
+	"encoding/json"
+	"testing"
+
+	networkv1 "github.com/mulgadc/spinifex/contracts/network/v1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestInternetGatewaySubjects(t *testing.T) {
+	assert.Equal(t, "vpc.igw-attach", networkv1.InternetGatewayAttachSubject)
+	assert.Equal(t, "vpc.igw-detach", networkv1.InternetGatewayDetachSubject)
+}
+
+func TestInternetGatewayEvent_JSON(t *testing.T) {
+	golden := `{"internet_gateway_id":"igw-1","vpc_id":"vpc-1"}`
+	evt := networkv1.InternetGatewayEvent{InternetGatewayId: "igw-1", VpcId: "vpc-1"}
+
+	marshaled, err := json.Marshal(evt)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(marshaled))
+
+	var decoded networkv1.InternetGatewayEvent
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, evt, decoded)
+}
@@ -0,0 +1,22 @@
+package networkv1
+
+const (
+	// NATAddSubject asks vpcd to commit the OVN dnat_and_snat rule.
+	// Request/reply, 45s timeout for the OVN flows barrier; some callers
+	// publish it fire-and-forget instead. See README for both paths.
+	NATAddSubject = "vpc.add-nat"
+
+	// NATDeleteSubject asks vpcd to delete the dnat_and_snat rule and
+	// unbind host plumbing. Request/reply, 15s timeout, retried on
+	// ErrNoResponders. See README for the retry budget.
+	NATDeleteSubject = "vpc.delete-nat"
+)
+
+// NATEvent is the payload on NATAddSubject and NATDeleteSubject.
+type NATEvent struct {
+	VpcId      string `json:"vpc_id"`
+	ExternalIP string `json:"external_ip"`
+	LogicalIP  string `json:"logical_ip"`
+	PortName   string `json:"port_name"`
+	MAC        string `json:"mac"`
+}
@@ -0,0 +1,25 @@
+package networkv1
+
+const (
+	// NATGatewayAddSubject asks vpcd to install the NAT Gateway's SNAT
+	// rule, and the per-subnet egress policy when SubnetId is set.
+	// Fire-and-forget.
+	NATGatewayAddSubject = "vpc.add-nat-gateway"
+
+	// NATGatewayDeleteSubject asks vpcd to remove the NAT Gateway's SNAT
+	// rule and per-subnet egress policy. Fire-and-forget.
+	NATGatewayDeleteSubject = "vpc.delete-nat-gateway"
+)
+
+// NATGatewayEvent is the payload on NATGatewayAddSubject and
+// NATGatewayDeleteSubject. SubnetId and DestinationCidr are omitempty
+// because one of today's two publishers (domains/ec2/natgw) never sets
+// them; omitting matches that publisher's wire bytes exactly. See README.
+type NATGatewayEvent struct {
+	VpcId           string `json:"vpc_id"`
+	NatGatewayId    string `json:"nat_gateway_id"`
+	PublicIp        string `json:"public_ip"`
+	SubnetCidr      string `json:"subnet_cidr"`
+	SubnetId        string `json:"subnet_id,omitempty"`
+	DestinationCidr string `json:"destination_cidr,omitempty"`
+}
@@ -0,0 +1,49 @@
+package networkv1_test
+
+import (
+	"encoding/json"
+	"testing"
+
+	networkv1 "github.com/mulgadc/spinifex/contracts/network/v1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNATGatewaySubjects(t *testing.T) {
+	assert.Equal(t, "vpc.add-nat-gateway", networkv1.NATGatewayAddSubject)
+	assert.Equal(t, "vpc.delete-nat-gateway", networkv1.NATGatewayDeleteSubject)
+}
+
+func TestNATGatewayEvent_JSON(t *testing.T) {
+	golden := `{"vpc_id":"vpc-1","nat_gateway_id":"nat-1","public_ip":"203.0.113.5","subnet_cidr":"10.0.1.0/24","subnet_id":"subnet-1","destination_cidr":"0.0.0.0/0"}`
+	evt := networkv1.NATGatewayEvent{
+		VpcId: "vpc-1", NatGatewayId: "nat-1", PublicIp: "203.0.113.5",
+		SubnetCidr: "10.0.1.0/24", SubnetId: "subnet-1", DestinationCidr: "0.0.0.0/0",
+	}
+
+	marshaled, err := json.Marshal(evt)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(marshaled))
+
+	var decoded networkv1.NATGatewayEvent
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, evt, decoded)
+}
+
+// TestNATGatewayEvent_NarrowPublisherShapeStillDecodes pins that the
+// narrower 4-field shape one of today's two publishers sends (domains/ec2/
+// natgw) round-trips exactly: SubnetId and DestinationCidr stay absent from
+// the wire on both the decode and the re-encode, not merely zero-valued.
+func TestNATGatewayEvent_NarrowPublisherShapeStillDecodes(t *testing.T) {
+	narrow := `{"vpc_id":"vpc-1","nat_gateway_id":"nat-1","public_ip":"203.0.113.5","subnet_cidr":"10.0.1.0/24"}`
+	var decoded networkv1.NATGatewayEvent
+	require.NoError(t, json.Unmarshal([]byte(narrow), &decoded))
+	want := networkv1.NATGatewayEvent{
+		VpcId: "vpc-1", NatGatewayId: "nat-1", PublicIp: "203.0.113.5", SubnetCidr: "10.0.1.0/24",
+	}
+	assert.Equal(t, want, decoded)
+
+	marshaled, err := json.Marshal(decoded)
+	require.NoError(t, err)
+	assert.JSONEq(t, narrow, string(marshaled))
+}
@@ -0,0 +1,31 @@
+package networkv1_test
+
+import (
+	"encoding/json"
+	"testing"
+
+	networkv1 "github.com/mulgadc/spinifex/contracts/network/v1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNATSubjects(t *testing.T) {
+	assert.Equal(t, "vpc.add-nat", networkv1.NATAddSubject)
+	assert.Equal(t, "vpc.delete-nat", networkv1.NATDeleteSubject)
+}
+
+func TestNATEvent_JSON(t *testing.T) {
+	golden := `{"vpc_id":"vpc-1","external_ip":"203.0.113.5","logical_ip":"10.0.1.5","port_name":"port-eni-1","mac":"02:00:00:00:00:01"}`
+	evt := networkv1.NATEvent{
+		VpcId: "vpc-1", ExternalIP: "203.0.113.5", LogicalIP: "10.0.1.5",
+		PortName: "port-eni-1", MAC: "02:00:00:00:00:01",
+	}
+
+	marshaled, err := json.Marshal(evt)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(marshaled))
+
+	var decoded networkv1.NATEvent
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, evt, decoded)
+}
@@ -0,0 +1,26 @@
+package networkv1
+
+const (
+	// PortCreateSubject asks vpcd to create the port's OVN logical switch
+	// port. Request/reply so an OVSDB failure surfaces to the caller rather
+	// than being swallowed; the deployed timeout is 5s.
+	PortCreateSubject = "vpc.create-port"
+
+	// PortDeleteSubject asks vpcd to remove the port's OVN logical switch
+	// port. Request/reply, 5s timeout, but the deployed caller treats
+	// failure as non-fatal and relies on the reconciler's orphan prune.
+	PortDeleteSubject = "vpc.delete-port"
+)
+
+// PortEvent is the payload on PortCreateSubject and PortDeleteSubject.
+// SecurityGroupIds and SuppressDHCP are meaningful on create only; delete
+// carries them zero-valued.
+type PortEvent struct {
+	NetworkInterfaceId string   `json:"network_interface_id"`
+	SubnetId           string   `json:"subnet_id"`
+	VpcId              string   `json:"vpc_id"`
+	PrivateIpAddress   string   `json:"private_ip_address"`
+	MacAddress         string   `json:"mac_address"`
+	SecurityGroupIds   []string `json:"security_group_ids,omitempty"`
+	SuppressDHCP       bool     `json:"suppress_dhcp,omitempty"`
+}
@@ -0,0 +1,14 @@
+package networkv1
+
+// PortSecurityGroupsUpdateSubject asks vpcd to reconcile a port's OVN
+// port-group memberships against a declarative list; vpcd computes the
+// diff. Request/reply, 5s timeout, errors propagate to the caller.
+const PortSecurityGroupsUpdateSubject = "vpc.update-port-sgs"
+
+// PortSecurityGroupsUpdateEvent is the payload on
+// PortSecurityGroupsUpdateSubject.
+type PortSecurityGroupsUpdateEvent struct {
+	NetworkInterfaceId string   `json:"network_interface_id"`
+	PrivateIpAddress   string   `json:"private_ip_address"`
+	SecurityGroupIds   []string `json:"security_group_ids"`
+}
@@ -0,0 +1,30 @@
+package networkv1_test
+
+import (
+	"encoding/json"
+	"testing"
+
+	networkv1 "github.com/mulgadc/spinifex/contracts/network/v1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestPortSecurityGroupsUpdateSubject(t *testing.T) {
+	assert.Equal(t, "vpc.update-port-sgs", networkv1.PortSecurityGroupsUpdateSubject)
+}
+
+func TestPortSecurityGroupsUpdateEvent_JSON(t *testing.T) {
+	golden := `{"network_interface_id":"eni-1","private_ip_address":"10.0.1.5","security_group_ids":["sg-1","sg-2"]}`
+	evt := networkv1.PortSecurityGroupsUpdateEvent{
+		NetworkInterfaceId: "eni-1", PrivateIpAddress: "10.0.1.5",
+		SecurityGroupIds: []string{"sg-1", "sg-2"},
+	}
+
+	marshaled, err := json.Marshal(evt)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(marshaled))
+
+	var decoded networkv1.PortSecurityGroupsUpdateEvent
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, evt, decoded)
+}
@@ -0,0 +1,44 @@
+package networkv1_test
+
+import (
+	"encoding/json"
+	"testing"
+
+	networkv1 "github.com/mulgadc/spinifex/contracts/network/v1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestPortSubjects(t *testing.T) {
+	assert.Equal(t, "vpc.create-port", networkv1.PortCreateSubject)
+	assert.Equal(t, "vpc.delete-port", networkv1.PortDeleteSubject)
+}
+
+func TestPortEvent_JSON(t *testing.T) {
+	golden := `{"network_interface_id":"eni-1","subnet_id":"subnet-1","vpc_id":"vpc-1","private_ip_address":"10.0.1.5","mac_address":"02:00:00:00:00:01","security_group_ids":["sg-1"],"suppress_dhcp":true}`
+	evt := networkv1.PortEvent{
+		NetworkInterfaceId: "eni-1", SubnetId: "subnet-1", VpcId: "vpc-1",
+		PrivateIpAddress: "10.0.1.5", MacAddress: "02:00:00:00:00:01",
+		SecurityGroupIds: []string{"sg-1"}, SuppressDHCP: true,
+	}
+
+	marshaled, err := json.Marshal(evt)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(marshaled))
+
+	var decoded networkv1.PortEvent
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, evt, decoded)
+}
+
+func TestPortEvent_OmitsEmptyFields(t *testing.T) {
+	golden := `{"network_interface_id":"eni-1","subnet_id":"subnet-1","vpc_id":"vpc-1","private_ip_address":"10.0.1.5","mac_address":"02:00:00:00:00:01"}`
+	evt := networkv1.PortEvent{
+		NetworkInterfaceId: "eni-1", SubnetId: "subnet-1", VpcId: "vpc-1",
+		PrivateIpAddress: "10.0.1.5", MacAddress: "02:00:00:00:00:01",
+	}
+
+	marshaled, err := json.Marshal(evt)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(marshaled))
+}
@@ -0,0 +1,8 @@
+// Package networkv1 is the versioned wire vocabulary for the vpc.*
+// control-plane-to-network-realisation boundary. See README.md for the
+// route table, ownership statement and compatibility rules.
+package networkv1
+
+// QueueGroup is the NATS queue group every vpcd subscribes under, so
+// exactly one vpcd instance processes a given event.
+const QueueGroup = "vpcd-workers"
@@ -0,0 +1,13 @@
+package networkv1_test
+
+import (
+	"testing"
+
+	networkv1 "github.com/mulgadc/spinifex/contracts/network/v1"
+	"github.com/stretchr/testify/assert"
+)
+
+// TestQueueGroup pins the queue group literal every vpcd subscribes under.
+func TestQueueGroup(t *testing.T) {
+	assert.Equal(t, "vpcd-workers", networkv1.QueueGroup)
+}
@@ -0,0 +1,39 @@
+package networkv1
+
+const (
+	// SecurityGroupCreateSubject asks vpcd to ensure the SG's port group
+	// then apply its ACL set. Request/reply, 5s timeout.
+	SecurityGroupCreateSubject = "vpc.create-sg"
+
+	// SecurityGroupDeleteSubject asks vpcd to remove the SG's port group
+	// and ACLs. Request/reply, 5s timeout, idempotent.
+	SecurityGroupDeleteSubject = "vpc.delete-sg"
+
+	// SecurityGroupUpdateSubject asks vpcd to replace the SG's ACL set.
+	// Request/reply, 5s timeout; the port group is unaffected.
+	SecurityGroupUpdateSubject = "vpc.update-sg"
+)
+
+// SecurityGroupRule is a security-group rule as EC2 stores it. Network's ACL
+// builder only reads IpProtocol, FromPort, ToPort, CidrIp and SourceSG; the
+// rest exist so the wire shape matches the publisher's stored record exactly.
+type SecurityGroupRule struct {
+	RuleId      string            `json:"rule_id"`
+	IpProtocol  string            `json:"ip_protocol"`
+	FromPort    int64             `json:"from_port"`
+	ToPort      int64             `json:"to_port"`
+	CidrIp      string            `json:"cidr_ip,omitempty"`
+	CidrIpv6    string            `json:"cidr_ipv6,omitempty"`
+	SourceSG    string            `json:"source_sg,omitempty"`
+	Description string            `json:"description,omitempty"`
+	Tags        map[string]string `json:"tags,omitempty"`
+}
+
+// SecurityGroupEvent is the payload on SecurityGroupCreateSubject,
+// SecurityGroupDeleteSubject and SecurityGroupUpdateSubject.
+type SecurityGroupEvent struct {
+	GroupId      string              `json:"group_id"`
+	VpcId        string              `json:"vpc_id"`
+	IngressRules []SecurityGroupRule `json:"ingress_rules,omitempty"`
+	EgressRules  []SecurityGroupRule `json:"egress_rules,omitempty"`
+}
@@ -0,0 +1,50 @@
+package networkv1_test
+
+import (
+	"encoding/json"
+	"testing"
+
+	networkv1 "github.com/mulgadc/spinifex/contracts/network/v1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestSecurityGroupSubjects(t *testing.T) {
+	assert.Equal(t, "vpc.create-sg", networkv1.SecurityGroupCreateSubject)
+	assert.Equal(t, "vpc.delete-sg", networkv1.SecurityGroupDeleteSubject)
+	assert.Equal(t, "vpc.update-sg", networkv1.SecurityGroupUpdateSubject)
+}
+
+func TestSecurityGroupEvent_JSON(t *testing.T) {
+	golden := `{"group_id":"sg-1","vpc_id":"vpc-1","ingress_rules":[{"rule_id":"sgr-1","ip_protocol":"tcp","from_port":22,"to_port":22,"cidr_ip":"0.0.0.0/0"}],"egress_rules":[{"rule_id":"sgr-2","ip_protocol":"-1","from_port":0,"to_port":0,"source_sg":"sg-2"}]}`
+	evt := networkv1.SecurityGroupEvent{
+		GroupId: "sg-1", VpcId: "vpc-1",
+		IngressRules: []networkv1.SecurityGroupRule{{RuleId: "sgr-1", IpProtocol: "tcp", FromPort: 22, ToPort: 22, CidrIp: "0.0.0.0/0"}},
+		EgressRules:  []networkv1.SecurityGroupRule{{RuleId: "sgr-2", IpProtocol: "-1", SourceSG: "sg-2"}},
+	}
+
+	marshaled, err := json.Marshal(evt)
+	require.NoError(t, err)
+	assert.JSONEq(t, golden, string(marshaled))
+
+	var decoded networkv1.SecurityGroupEvent
+	require.NoError(t, json.Unmarshal([]byte(golden), &decoded))
+	assert.Equal(t, evt, decoded)
+}
+
+// TestSecurityGroupRule_FullShapeRoundTrip pins the EC2 publisher's stored
+// rule shape (rule_id, cidr_ipv6, description, tags) round-tripping losslessly;
+// network's ACL builder still only reads the first five fields.
+func TestSecurityGroupRule_FullShapeRoundTrip(t *testing.T) {
+	wider := `{"rule_id":"sgr-1","ip_protocol":"tcp","from_port":22,"to_port":22,"cidr_ip":"0.0.0.0/0","cidr_ipv6":"::/0","description":"ssh","tags":{"k":"v"}}`
+	var decoded networkv1.SecurityGroupRule
+	require.NoError(t, json.Unmarshal([]byte(wider), &decoded))
+	assert.Equal(t, networkv1.SecurityGroupRule{
+		RuleId: "sgr-1", IpProtocol: "tcp", FromPort: 22, ToPort: 22, CidrIp: "0.0.0.0/0",
+		CidrIpv6: "::/0", Description: "ssh", Tags: map[string]string{"k": "v"},
+	}, decoded)
+
+	marshaled, err := json.Marshal(decoded)
+	require.NoError(t, err)
+	assert.JSONEq(t, wider, string(marshaled))
+}
--- a/Show More
+++ b/Show More