From e6eaf9846c809d6b3966a2ae1810dcebb69b2a80 Mon Sep 17 00:00:00 2001 From: joshsiv-mulga Date: Tue, 29 Sep 2026 09:00:04 +1000 Subject: [PATCH] docs: record package-boundary entry-point inventory --- CONTRIBUTING.md | 1 + docs/PACKAGE_BOUNDARY_MIGRATION.md | 96 ++++++++++++++++++++++++++++++ 2 files changed, 97 insertions(+) create mode 100644 docs/PACKAGE_BOUNDARY_MIGRATION.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d0503d892..280fda9d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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). diff --git a/docs/PACKAGE_BOUNDARY_MIGRATION.md b/docs/PACKAGE_BOUNDARY_MIGRATION.md new file mode 100644 index 000000000..6bfed6e9c --- /dev/null +++ b/docs/PACKAGE_BOUNDARY_MIGRATION.md @@ -0,0 +1,96 @@ +# Package-boundary migration record + +**Status:** Active implementation record. +**Decision:** [Mulga ADR-0001 — Spinifex Package Boundary and Layout](https://github.com/mulgadc/mulga/blob/main/docs/adr/0001-spinifex-package-boundary-layout.md). +**Scope:** Spinifex source layout only. This record does not establish a new +architecture decision, expand a customer-facing interface, or claim that the +current implementation conforms to the target layout. + +## Purpose + +This document records the implementation sequence for ADR-0001 in this +repository. The ADR owns the target layout and dependency rules; this record +captures the source-level entry-point inventory and the evidence needed for +each narrow structural slice. + +The migration proceeds on one long-lived refactor branch. Each commit remains +small, independently buildable and reviewable; that does not require one pull +request per package move. + +## Baseline + +The inventory below was taken from Spinifex commit +`ecef5e4d2f793b4cf2c96d0a43d0a1ab37be3eed`, the revision pinned by Mulga when +ADR-0001 was accepted. It records ownership standing, not a promise that a +binary or script is AWS-compatible or supported beyond its documented scope. + +## Entry-point and automation inventory + +### Product operator and delivery entry points + +| Current path | Standing | Target ownership | Migration rule | +|---|---|---|---| +| `cmd/spinifex` (`spx`) | Supported operator process | Thin main; command assembly in `spinifex/operator/cli` and individual supported use cases in `spinifex/operator/*` | Preserve binary and supported command compatibility. The CLI must reach a domain through an explicit capability, never its private state. | +| `cmd/installer` | Delivery executable | Thin main; interactive, unattended and host-installation work in `spinifex/operator/installer` | Preserve installation behaviour while separating executable startup from delivery logic. It is not, merely by existing, the permanent administration interface. | + +`cmd/spinifex/cmd` and `cmd/installer/*` are presently implementation-bearing +trees, not thin entry points. They are not moved until their individual +receiving owners and test seams are selected. + +### Guest and named-role entry points + +| Current path | Standing | Target ownership | Evidence of role boundary | +|---|---|---|---| +| `cmd/ecs-agent` | ECS guest agent | Thin main; `spinifex/agents/ecs` | Baked into ECS node images; communicates with the control plane through the AWS gateway, not NATS. | +| `cmd/rds-agent` | RDS guest agent | Thin main; `spinifex/agents/rds` | Runs in an RDS guest, handles bootstrap and engine directives through the gateway. | +| `cmd/lb-agent` | ELBv2 guest agent | Thin main; `spinifex/agents/elbv2` | Included in the load-balancer microVM and controls its local data plane. | +| `cmd/eks-token-webhook` | EKS control-plane guest role | Thin main; `spinifex/agents/eks/tokenwebhook` | Baked into the EKS node image as the Kubernetes TokenReview webhook. | +| `cmd/eks-gateway-fetch` | EKS control-plane guest helper | Thin main; `spinifex/agents/eks/gatewayfetch` | Fetches recovery and addon state through the AWS gateway. | +| `cmd/eks-gateway-publish` | EKS control-plane guest helper | Thin main; `spinifex/agents/eks/gatewaypublish` | Relays bootstrap and state reports through the AWS gateway. | +| `cmd/eks-webhook-cert` | EKS image-resident certificate helper | Thin main; `spinifex/agents/eks/webhookcert` | Invoked by EKS image scripts to create/reuse webhook serving certificates. | +| `cmd/eks-konnectivity-cert` | EKS image-resident certificate helper | Thin main; `spinifex/agents/eks/konnectivitycert` | Invoked by EKS image scripts to create/reuse Konnectivity serving certificates. | +| `cmd/ecr-credential-provider` | EKS node integration | Thin main; `spinifex/agents/eks/credentialprovider` | Kubelet exec credential provider baked into EKS images; it is not ECR control-plane ownership. | + +No common agent package is introduced by this inventory. Shared mechanisms are +considered only when the existing role and least-privilege boundaries remain +intact; ADR-0001 explicitly defers that design. + +### Development and qualification entry points + +| Current path | Standing | Target ownership | Rule | +|---|---|---|---| +| `cmd/aws-model-coverage` | Qualification generator | Thin main; reusable code in `internal/tooling` | Produces the dispatch-versus-model inventory; never imported by product packages. | +| `cmd/dhcptest` | Development diagnostic | Thin main; reusable code in `internal/tooling` if extraction is useful | It is a DHCP probe, not a supported `spx admin` command. | +| `cmd/spx-loadgen` | Qualification/load tool | Thin main; reusable code in `internal/testkit` | It drives test load and is not shipped to nodes. | +| `tests/e2e/*/cmd/*`, `tests/bench/*/cmd/*` | Test and benchmark-private tools | Remain test-private | They are invoked by a test or benchmark harness, not a product process. | +| `docs/terraform-workbooks/demo-app/main.go` | Demonstration workload | Remain with the workbook | It is neither a Spinifex executable nor a product package. | + +### Automation standing + +| Path class | Standing | Rule during migration | +|---|---|---| +| `.github/scripts/` | CI-private qualification automation | Keep at the module root; the invoking workflow owns the evidence scope. | +| `build/`, `images/`, `scripts/images/`, image build and publish scripts | Delivery and guest-image inputs | Keep at the module root. In-guest helpers stay with their image; do not relocate shell sources into Go packages. | +| `scripts/setup.sh`, `setup-ovn.sh`, `install-node.sh`, `node-reset.sh`, `uninstall-spx.sh` | Transitional delivery and documented host-operation mechanics | Keep at the module root. They may implement a published procedure but are not an enduring public administration API solely because they are installed on a node. | +| `scripts/dev-env/`, `scripts/demo/`, benchmarks, diagnostics and Terraform experiments | Development or exploratory automation | Keep at the module root; they are not customer-facing contracts. | +| `scripts/check-coverage.sh`, `diff-coverage.sh`, `run-gate.sh`, `sync-aws-models.sh` and test harness scripts | Repository and qualification automation | Keep at the module root; their caller defines the contract and evidence. | + +## First source move + +The first source move remains the cohesive ARN leaf package: + +- old import path: `github.com/mulgadc/spinifex/spinifex/arn` +- target import path: `github.com/mulgadc/spinifex/spinifex/foundation/aws/arn` + +It changes no behaviour, leaves no forwarding package, updates every importer, +runs the package and direct-caller tests, and proves the old path is absent. +The inventory is intentionally committed before this move so a later thin-main +refactor cannot silently choose an owner by convenience. + +## Recording rule + +For every later slice, add the old and new path, source commit, focused +verification, and any finding exposed by the move. Record a conflict rather +than folding a behavioural repair into a structural commit. When this branch +is merged, the umbrella repository's execution plan records the resulting +Spinifex commit.