From 2663bf563b092d38599f9e7e0eef8dc207b2f5c0 Mon Sep 17 00:00:00 2001 From: joshsiv-mulga Date: Tue, 6 Oct 2026 12:41:35 +1000 Subject: [PATCH] docs: record guest metadata move and dependency-rule debt --- docs/PACKAGE_BOUNDARY_MIGRATION.md | 33 ++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/docs/PACKAGE_BOUNDARY_MIGRATION.md b/docs/PACKAGE_BOUNDARY_MIGRATION.md index b198aae54..495d887cd 100644 --- a/docs/PACKAGE_BOUNDARY_MIGRATION.md +++ b/docs/PACKAGE_BOUNDARY_MIGRATION.md @@ -241,6 +241,13 @@ while the branch is in flight; they do not describe the umbrella repository's | `53f13f213` | `spinifex/utils` (`GenerateResourceID`) | `spinifex/foundation/aws/identifiers` | AWS-style `{prefix}-{17 hex}` resource-ID generation joins the AWS identifier foundation beside request-ID normalisation; callers use the established `awsidentifiers` alias, which also avoids the network-identifier package name. Format and CSPRNG failure handling are unchanged. Full preflight (excluding the pre-existing containerd advisory), focused tests and tagged integration/E2E compilation passed. | | `eab631b42` | `spinifex/services/predastore` | `spinifex/runtime/roles/predastore` | Predastore process configuration and startup are a named runtime role; the package holds no S3 resource semantics. The service manifest path moved with it. Full preflight (excluding the pre-existing containerd advisory), focused role, role-catalogue and CLI suites, and tagged integration/E2E compilation passed. Commit `796fb52d4` separately corrects the manifest's stale `handlers/acm` path left by the ACM relocation; `manifest-check` now passes. | | `ad6a158f8` | `spinifex/services/northstar` | `spinifex/runtime/roles/northstar` | Northstar process startup and reload are a named runtime role. `BootstrapBaseZone` moved with it unchanged but is DNS control-plane work (it imports `handlers/dns`); it belongs to `domains/dns` when that domain moves, so the role is not yet thin. Full preflight (excluding the pre-existing containerd advisory), focused role, role-catalogue and CLI suites, `manifest-check` and tagged integration/E2E compilation passed. | +| `931d86d5c` | `spinifex/services/awsgw` | `spinifex/runtime/roles/awsgw` | The AWS gateway process is a named runtime role and its composition root wires every domain, which runtime may do. The quota reconcile loop (`runQuotaReconcile`, `quotaKeyFor`) moved with it unchanged but belongs to `domains/admission/quota`, and the EKS token-verify responder belongs with STS or EKS identity; both are recorded residuals, so the role is not yet thin. Service-interface manifest, design doc and architecture diagram paths were updated. Full preflight (excluding the pre-existing containerd advisory), focused role, role-catalogue and CLI suites, `manifest-check` and tagged integration/E2E compilation passed. | +| `745338563` | `spinifex/utils` (`GenerateErrorPayload`, `GenerateErrorPayloadWithMessage`, `ValidateErrorPayload`, `UnmarshalJsonPayload`) | `spinifex/foundation/aws/errors` | The JSON error envelope every domain exchanges over NATS carries the shared AWS error vocabulary, so it sits beside the codes it encodes rather than in a per-domain contract. Behaviour is unchanged. Full preflight (excluding the pre-existing containerd advisory), focused error and caller suites and tagged integration/E2E compilation passed. | +| `02e0dd0dc` | `spinifex/utils` (`GlobalAccountID`, `IsAccountID`) | `spinifex/foundation/aws/identifiers` | The 12-digit account ID check and the system account ID constant are AWS identifier vocabulary and sit beside resource ID generation; no account policy changed. Full preflight (excluding the pre-existing containerd advisory), focused identifier and caller suites and tagged integration/E2E compilation passed. | +| `b5806ce63` | `spinifex/utils` (NATS connect/retry, request/serve, gather, headers, `PublishEvent`, trace propagation) | `spinifex/foundation/messaging/nats` (package `natsmsg`) | Generic NATS transport primitives are shared machinery with no resource owner; the package name avoids colliding with `nats.go` at every caller. The OTel instrumentation scope keeps its `spinifex/utils` value so existing APM queries still match. vpcd's request/ack protocol (`RequestEvent`, `AddNAT`, `PublishNATEvent`) stays in `utils/vpcd_event.go` for a future network contract, and `SubjectEnsureDefaultVpc` stays in `utils/ec2_subject.go` for an EC2 contract; both were split out byte-identical. Full preflight (excluding the pre-existing containerd advisory), focused transport and caller suites and tagged integration/E2E compilation passed. | +| `cabe0e99b` | `spinifex/handlers/sysinstance` | `spinifex/domains/ec2/systeminstance` | System-instance launch is compute ownership; managed services (ELBv2, EKS, RDS, Bedrock) consume the launcher contract. The package was renamed to its directory; runtime `sysinstance:` error strings are unchanged. Managed-service parent metadata is still only the `ManagedBy` tag value, short of the explicit parent metadata the ADR names. Full preflight (excluding the pre-existing containerd advisory), focused daemon and managed-service suites and tagged integration/E2E compilation passed. | +| `4d86296eb` | `spinifex/handlers/systemvpc` | `spinifex/domains/network/systemvpc` | Managed system-VPC realisation is network ownership; ELBv2, EKS, RDS and Bedrock consume its builder. The package was renamed from `handlers_systemvpc` to its directory and callers dropped the alias; it depends only on foundation packages. Full preflight (excluding the pre-existing containerd advisory), focused system-VPC, daemon and managed-service suites and tagged integration/E2E compilation passed. | +| `09de514ef` | `spinifex/handlers/imds` | `spinifex/domains/ec2/guestmetadata` | Guest metadata is a compute-domain interface served to guests on each node. The package was renamed from `handlers_imds` to its directory and its vpcd and E2E callers dropped the alias; five path comments were updated. The move exposes dependency-rule breaks it does not repair: imports of the DNS, EC2 instance, EC2 key, IAM and STS implementations, and the first domain-to-runtime edge (`runtime/compute/vm`); see Guest metadata relocation residuals. Full preflight (excluding the pre-existing containerd advisory), focused guest-metadata, vpcd and DNS suites and tagged integration/E2E compilation passed. | The EC2 contract row is intentionally different from the directory moves: it creates a compatibility boundary. `ec2.cmd.*` retains its deployed one-token NATS @@ -295,6 +302,26 @@ changing their behaviour in a structural slice: service registration itself needs the later ingress registration contract; it is not hidden by a compatibility shim in this move. +### Guest metadata relocation residuals + +The guest-metadata move keeps every existing import unchanged, so the domain package now shows these breaks of the target dependency rules. +Each needs a consumer-owned capability, projection or versioned contract before the dependency lint (ADR step 8) can be enabled. + +- `domains/ec2/guestmetadata` imports the DNS, EC2 instance, EC2 key, IAM and STS implementations, which breaks rule 3 (no domain reads another domain's implementation). +- `domains/ec2/guestmetadata` imports `runtime/compute/vm` for instance records and VM reconstruction, the first domain-to-runtime edge; runtime is meant to compose domains, not be imported by them. + +### Dependency-rule debt to clear after the moves + +These residuals were recorded by individual slices and must be resolved once the structural moves are complete, before the dependency lint is enabled. + +- Guest metadata: the cross-domain and runtime imports above. +- ACM: the IAM AES-GCM helper import and gateway-owned action dispatch (ACM relocation residuals). +- `runtime/roles/northstar`: `BootstrapBaseZone` is DNS control-plane work that belongs to `domains/dns`. +- `runtime/roles/awsgw`: the quota reconcile loop belongs to `domains/admission/quota`, and the EKS token-verify responder belongs with STS or EKS identity. +- `utils`: `vpcd_event.go` (vpcd request/ack protocol and NAT helpers) awaits a network contract, `ec2_subject.go` awaits an EC2 contract, and `encryption.go` and `tagmirror.go` await the EC2/EBS slices. +- `runtime/compute/cache.New`: two construction-time panics carry a lint exemption pending a constructor that returns an error. +- `domains/ec2/systeminstance`: managed-service parent metadata is only the `ManagedBy` tag value. + ## Recording rule For every later slice, add the old and new path, source commit, focused @@ -302,9 +329,3 @@ 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. -| `931d86d5c` | `spinifex/services/awsgw` | `spinifex/runtime/roles/awsgw` | The AWS gateway process is a named runtime role and its composition root wires every domain, which runtime may do. The quota reconcile loop (`runQuotaReconcile`, `quotaKeyFor`) moved with it unchanged but belongs to `domains/admission/quota`, and the EKS token-verify responder belongs with STS or EKS identity; both are recorded residuals, so the role is not yet thin. Service-interface manifest, design doc and architecture diagram paths were updated. Full preflight (excluding the pre-existing containerd advisory), focused role, role-catalogue and CLI suites, `manifest-check` and tagged integration/E2E compilation passed. | -| `745338563` | `spinifex/utils` (`GenerateErrorPayload`, `GenerateErrorPayloadWithMessage`, `ValidateErrorPayload`, `UnmarshalJsonPayload`) | `spinifex/foundation/aws/errors` | The JSON error envelope every domain exchanges over NATS carries the shared AWS error vocabulary, so it sits beside the codes it encodes rather than in a per-domain contract. Behaviour is unchanged. Full preflight (excluding the pre-existing containerd advisory), focused error and caller suites and tagged integration/E2E compilation passed. | -| `02e0dd0dc` | `spinifex/utils` (`GlobalAccountID`, `IsAccountID`) | `spinifex/foundation/aws/identifiers` | The 12-digit account ID check and the system account ID constant are AWS identifier vocabulary and sit beside resource ID generation; no account policy changed. Full preflight (excluding the pre-existing containerd advisory), focused identifier and caller suites and tagged integration/E2E compilation passed. | -| `b5806ce63` | `spinifex/utils` (NATS connect/retry, request/serve, gather, headers, `PublishEvent`, trace propagation) | `spinifex/foundation/messaging/nats` (package `natsmsg`) | Generic NATS transport primitives are shared machinery with no resource owner; the package name avoids colliding with `nats.go` at every caller. The OTel instrumentation scope keeps its `spinifex/utils` value so existing APM queries still match. vpcd's request/ack protocol (`RequestEvent`, `AddNAT`, `PublishNATEvent`) stays in `utils/vpcd_event.go` for a future network contract, and `SubjectEnsureDefaultVpc` stays in `utils/ec2_subject.go` for an EC2 contract; both were split out byte-identical. Full preflight (excluding the pre-existing containerd advisory), focused transport and caller suites and tagged integration/E2E compilation passed. | -| `cabe0e99b` | `spinifex/handlers/sysinstance` | `spinifex/domains/ec2/systeminstance` | System-instance launch is compute ownership; managed services (ELBv2, EKS, RDS, Bedrock) consume the launcher contract. The package was renamed to its directory; runtime `sysinstance:` error strings are unchanged. Managed-service parent metadata is still only the `ManagedBy` tag value, short of the explicit parent metadata the ADR names. Full preflight (excluding the pre-existing containerd advisory), focused daemon and managed-service suites and tagged integration/E2E compilation passed. | -| `4d86296eb` | `spinifex/handlers/systemvpc` | `spinifex/domains/network/systemvpc` | Managed system-VPC realisation is network ownership; ELBv2, EKS, RDS and Bedrock consume its builder. The package was renamed from `handlers_systemvpc` to its directory and callers dropped the alias; it depends only on foundation packages. Full preflight (excluding the pre-existing containerd advisory), focused system-VPC, daemon and managed-service suites and tagged integration/E2E compilation passed. |