2 Commits

Author	SHA1	Message	Date
Josh Siviour	b5879f44ff	ADR-0001 package-boundary migration checkpoint (#1190) ... * refactor: move telemetry file naming to contract * docs: record telemetry contract move * refactor: move aws xml response helpers * docs: record aws xml helper move * refactor: move aws tag projections to foundation * docs: record aws tag projection move * refactor: move account key to state foundation * docs: record account key state move * refactor: move host privilege escalation to runtime * docs: record host privilege move * chore: resolve lint findings from package-boundary moves * refactor: move process supervision helpers to runtime host * docs: record process supervision move * refactor: move nbd endpoint helpers to compute runtime * docs: record nbd endpoint move * refactor: move image catalogue to operator * docs: record image catalogue move * refactor: move resource id generation to aws foundation * docs: record resource id move * refactor: move predastore role to runtime roles * docs: point service manifest at acm domain * docs: record predastore role move * refactor: move northstar role to runtime roles * docs: record northstar role move * refactor: move awsgw role to runtime roles * docs: record awsgw role move * refactor: move error payload helpers to aws errors * docs: record error payload move * refactor: move account identifiers to aws identifiers * docs: record account identifier move * refactor: move NATS transport to messaging foundation * docs: record NATS transport move * refactor: move system instance contract to EC2 domain * docs: record system instance move * refactor: move system VPC builder to network domain * docs: record system VPC move * refactor: move instance metadata service to EC2 domain * docs: record guest metadata move and dependency-rule debt * refactor: move DNS control plane to DNS domain * docs: record DNS domain move * refactor: move base zone bootstrap to DNS domain * docs: record base zone bootstrap move * refactor: replace SystemAccountID with GlobalAccountID * docs: record SystemAccountID removal * refactor: extract CA key-pair loader to foundation pki * docs: record foundation pki extraction * refactor: move tenant CA paths to ACM domain * docs: record tenant CA path move * refactor: move IPsec certificate handling to network host * docs: record IPsec certificate move * refactor: move Ochre serving lifecycle to the Ochre domain handlers/bedrock becomes domains/ochre. Ochre is the platform service; Bedrock names only its AWS API surface. Persisted and observable identifiers keep their bedrock names. * docs: record Ochre domain move * refactor: move Ochre vector store to the Ochre domain handlers/ochrevector becomes domains/ochre/vector. Callers import it as ochrevector because vector is a common local name in the gateway. * docs: record Ochre vector store move * refactor: move Hugging Face Hub client to the Ochre domain gateway/bedrock/hfhub becomes domains/ochre/hfhub. Its only caller is the spx admin ochre weights pull. * docs: record Hugging Face Hub client move and Ochre gateway debt * refactor: move EC2 tag mutation helpers to the EC2 domain utils/tagmirror.go becomes domains/ec2/tagmirror. It is EC2-wide tag mutation behaviour, and the tags resource package cannot host it without a resource-to-resource import cycle. * docs: record EC2 tag mutation move and migrate split finding * refactor: move network packages under the network domain Move spinifex/network/* to spinifex/domains/network/* as one enclosing move so the L0-L5 layer invariants keep classifying every package from a single root. Package names and dependency direction are unchanged; invariant scan roots, the RG-10 sudo allow-list path, CODEOWNERS and the repo-root walk in the IMDS netns unit test follow the new path. * docs: record network domain move * refactor: move standalone EC2 resource packages to the EC2 domain Move handlers/ec2/{account,key,launchtemplate,placementgroup, spotinstance,volumestate} to domains/ec2/<resource>. Each package is named after its directory and callers import it as ec2<resource>; volumestate already carried its directory name. * docs: record standalone EC2 resource moves * refactor: move EC2 VPC networking packages to the EC2 domain Move handlers/ec2/{vpc,eigw,eip,igw,natgw,routetable} to domains/ec2/<resource>, each named after its directory and imported as ec2<resource>. The reconcile drift-watch source scan now matches the ec2<resource> bucket qualifiers; its rule is unchanged. * docs: record EC2 VPC networking moves * refactor: move EC2 compute and storage packages to the EC2 domain Move handlers/ec2/{instance,volume,snapshot,image,tags} to domains/ec2/<resource>, each named after its directory and imported as ec2<resource>, which empties handlers/ec2. The daemon's e2e suite selection now lists the moved EC2 resource paths in place of handlers/ec2, so EC2-only changes select the daemon suites again. * docs: record EC2 compute and storage moves * refactor: move ECR credential provider to the EKS agent tree Move the kubelet exec credential provider implementation from cmd/ecr-credential-provider to agents/eks/credentialprovider, exposing one Main(in, out) entry point. The binary keeps its name and FIPS boot import as a thin main. Moving out of cmd/ brings the code under gosec; the one G101 hit on the kubelet API version constant is annotated. * docs: record ECR credential provider move * refactor: move EKS gateway publish helper to the EKS agent tree Move the eks-gateway-publish implementation to agents/eks/gatewaypublish behind Run(ctx, Config) error. The binary keeps flag definitions, environment defaults, parsing, its log prefix and exit code; each former fatal site returns an error with the same text. The retry wait now also honours context cancellation, which the binary never triggers. * docs: record EKS gateway publish move * refactor: move EKS gateway fetch helper to the EKS agent tree Move the eks-gateway-fetch implementation to agents/eks/gatewayfetch behind Run(ctx, Config) error, writing its TSV to Config.Out. The binary keeps flag definitions, environment defaults, parsing, its log prefix and exit code; each former fatal site returns an error with the same text. * docs: record EKS gateway fetch move * refactor: move EKS webhook cert helper to the EKS agent tree cmd/eks-webhook-cert keeps flag parsing, the log prefix and the exit; agents/eks/webhookcert owns Config and Run. Output, error text, file modes and exit codes are unchanged. * docs: record EKS webhook cert move * refactor: move EKS konnectivity cert helper to the EKS agent tree cmd/eks-konnectivity-cert keeps flag parsing, the log prefix and the exit; agents/eks/konnectivitycert owns Config and Run. Output, error text, file modes and exit codes are unchanged. * docs: record EKS konnectivity cert move * refactor: move EKS token webhook to the EKS agent tree cmd/eks-token-webhook keeps the -addr flag, environment-derived config, logging setup and exits; agents/eks/tokenwebhook owns Config and Run. The handlers/eks TokenReview result type stays as recorded temporary debt. * docs: record EKS token webhook move * refactor: move ECS agent runtime and credentials packages to the ECS agent tree * docs: record ECS agent subpackage move * refactor: move ECS agent implementation to the ECS agent tree cmd/ecs-agent keeps process lifecycle: signal context, the separate New and Run calls, both failure log lines, the exit and the ldflags-set build version, now passed in through Config.AgentVersion. agents/ecs/agent owns Config, LoadConfig and the agent. * docs: record ECS agent move * refactor: move RDS guest agent to agents/rds/agent * docs: record RDS guest agent move * refactor: move installer packages to operator/installer * docs: record installer move * refactor: move spx command tree to operator/cli Moving the command tree out of cmd/ brings it under errcheck and gosec. Flag and config wiring now fails loudly instead of silently dropping a binding, listing commands fail when they cannot write their table, and the formation server's unauthenticated TLS is annotated as a known gap. * docs: record spx command tree move * chore: accept known vulnerabilities with an expiry The vulnerability scan failed preflight on a containerd advisory that dev already carries and that is deferred to a separate dependency update. The gate now passes only reachable findings listed with an expiry date, fails on any new one or on an expired acceptance, and warns when an acceptance is no longer needed. * refactor: move EC2 account action adapters to domains/ec2/awsapi * refactor: move EC2 capacityreservation action adapters to domains/ec2/awsapi * refactor: move EC2 key action adapters to domains/ec2/awsapi * refactor: move EC2 launchtemplate action adapters to domains/ec2/awsapi * refactor: move EC2 placementgroup action adapters to domains/ec2/awsapi * docs: record EC2 standalone action adapter moves * refactor: move EC2 zone action adapters to domains/ec2/awsapi * refactor: move EC2 vpc action adapters to domains/ec2/awsapi * refactor: move EC2 eigw action adapters to domains/ec2/awsapi * refactor: move EC2 eip action adapters to domains/ec2/awsapi * refactor: move EC2 igw action adapters to domains/ec2/awsapi * refactor: move EC2 natgw action adapters to domains/ec2/awsapi * refactor: move EC2 routetable action adapters to domains/ec2/awsapi * docs: record EC2 VPC networking action adapter moves * refactor: move EC2 image action adapters to domains/ec2/awsapi * refactor: move EC2 snapshot action adapters to domains/ec2/awsapi * refactor: move EC2 volume action adapters to domains/ec2/awsapi * refactor: move EC2 tags action adapters to domains/ec2/awsapi * docs: record EC2 storage and tag action adapter moves * refactor: move EC2 resource authorization scopes to domains/ec2/awsapi * refactor: move EC2 idempotency adapter to domains/ec2/awsapi * refactor: move EC2 instance action adapters to domains/ec2/awsapi * refactor: move EC2 spotinstance action adapters to domains/ec2/awsapi * docs: record EC2 instance action adapter moves * refactor: move AWS REST-JSON router to ingress/aws/rest * refactor: move SigV4 auth-failure rate limiter to ingress/aws/ratelimit * docs: record AWS ingress helper moves and tooling conformance * docs: correct historical lifecycle references * test: characterize ECR control-plane dispatch before registration seam * feat: add AWS ingress service registration contract * docs: record ingress registration phases 0 and 1 * refactor: route registered AWS services through the ingress dispatch registry The gateway now consumes ingress/aws/dispatch. A registered service is accepted by the auth gate, resolves its own action label, renders errors in its declared envelope and is dispatched with an authenticated Invocation (account, region, policy authorisation and a lazy verified actor). Every other service keeps the existing switch, now named as the legacy path. The awsgw role wires an empty registry and refuses to start if a registered name is also served by the legacy table. No service is registered yet, so behaviour for every existing service is unchanged. * docs: record ingress dispatch registry consumption * refactor: register the ECR control plane from its domain domains/ecr/awsapi now registers the "ecr" AWS JSON 1.1 surface with the ingress dispatch registry: action resolution, resource scope, authorisation through the invocation, the composed capabilities and the success writer all live with the domain. The awsgw role is the only serving composition point; the gateway no longer imports the ECR API package and ECR leaves the legacy service table, JSON error table and dispatch switch. The OCI /v2 route is unchanged. Operation coverage reads ECR's declared inventory, which the registration uses verbatim; coverage.json is byte-identical. * docs: record ECR control-plane registration * fix: compose the ECR control plane in the integration harness The harness stopped wiring ECR's composed capabilities when the authorization-token action was composed, so every integration test that creates a repository or mints a token got ServerInternal. It now composes ECR as the awsgw role does, sharing the OCI registry, meta store and token issuer the /v2 data plane uses. * docs: record ingress pipeline deferral * refactor: extract AWS error envelope rendering to ingress ingress/aws/envelope owns the EC2, IAM-style and S3 XML error envelopes, the AWS JSON 1.1 error body and X-Amzn-Errortype value, the JSON-protocol header detector and the two error content types. Each shape keeps its own builder. The gateway error writers, ErrorHandler and the legacy per-service envelope selection stay in gateway and call the new package; gateway/eks renders its JSON errors through it directly. A 140-case status/header/body golden comparison across services and error writers was identical before and after. * docs: record error envelope extraction * refactor: move AWS service selection into ingress dispatch Selector answers served, action, error protocol, registered entry and startup overlap. The gateway supplies its legacy tables through the dispatch.Legacy interface; legacy dispatch and invocation building stay in gateway. * docs: record ingress service selection move * test: characterize ACM control-plane dispatch before registration Pins full-pipeline error envelopes, a successful action, target parsing agreement between dispatch and telemetry, authorization before the NATS call, 413 and 503 paths, throttle/trace/audit action and the inventory. * refactor: register ACM control plane from its domain domains/acm/awsapi registers the acm JSON 1.1 surface through the ingress dispatch registry, wired by the awsgw role. The gateway drops ACM_Request, the ACM action table and every legacy acm entry; the import invariant now covers each registered domain. * docs: record ACM registration * docs: record ECS, EKS and RDS source inventory and first-resource ranking * docs: record EKS control-plane secrets persisted in the cluster record * chore: drop containerd advisory acceptance now that dev ships v2.4.1 * test: characterize RDS DB subnet group lifecycle before extraction * docs: record RDS DB subnet group lifecycle contract * refactor: extract the RDS DB subnet group lifecycle owner domains/rds/subnetgroup owns the db-subnet-groups/{name} record, member subnet validation and the delete in-use guard. handlers/rds keeps AWS validation, projection and paging and binds two consumer-owned capabilities: the owner's Dependants (instances naming the group) and the instance side's subnetGroupPlacement. Stored shape and behaviour are unchanged. * docs: record RDS DB subnet group owner extraction * docs: correct RDS subnet group tagging debt and conformance scope * test: characterize ECS task definition lifecycle before extraction * docs: record ECS task definition lifecycle contract * refactor: extract ECS task definition owner into domains/ecs/taskdefinition Move the task definition record, container types, keys, reference parsing, ARN helpers and the register/deregister/resolve/list logic into a resource owner package. Stored JSON field names and KV keys are unchanged, and revision allocation keeps its existing non-atomic read-then-write. The owner declares its own PortMapping and SystemControl persisted types so it no longer depends on handlers/ecs/bus; the handler translates them onto the assign payload. Task and service launches reach task definitions only through a launch-side taskDefinitionResolver. AWS conversion, the guest projection and tags stay in handlers/ecs, and gateway authz only switches to the moved reference/ARN helpers. List handlers/ecs and the new package under spinifex_daemon so ECS-only changes select e2e-ecs. * docs: record ECS task definition owner extraction * test: characterize EKS access entry lifecycle before extraction * docs: record EKS access entry lifecycle contract * refactor: extract EKS access entry owner into domains/eks/access Move the access entry record, associated policy and scope types, keys, PrincipalARNHash, the policy catalogue and group mapping into a resource owner package. Stored JSON field names and KV keys are unchanged. Owner is the only writer: Create, SeedCreatorAdmin, Update, Associate, Disassociate and Delete carry the existing logic verbatim, and the put, compare-and-set and delete primitives are private. The handler keeps AWS validation, the cluster existence check, error mapping and projection. Token review still reads records through the exported Get, and the cluster prefix purge still sweeps entry keys. List handlers/eks and the new package under spinifex_daemon so EKS-only changes select the EKS suites. * docs: record EKS access entry owner extraction * test: characterize RDS engine catalogue before extraction * fix: return InvalidParameterValue for a missing RDS master password ValidateMasterUserPassword built the empty-password error with a bare errors.New carrying the code only in its text, which awserrors does not resolve, so CreateDBInstance without MasterUserPassword returned HTTP 500 ServerInternal. Build it with awserrors.Errorf like the other branches so the gateway returns 400 InvalidParameterValue, and cover the full gateway to RDS service path with a regression test. * docs: record RDS engine catalogue boundary and evidence * refactor: extract RDS engine catalogue into domains/rds/engine Move engine identity and validation, the per-engine parameter catalogues, effective-parameter resolution, db.* instance classes and engine/orderable selection into an engine package. Behaviour, error codes and ordering are unchanged. The package imports no EC2 package: instance-class memory comes from an immutable Sizing value built from an engine-declared InstanceTypes interface, backed by the fixed instance-type table in handlers/rds. Effective parameters leave as an engine-owned Setting, converted to Parameter in handlers/rds. AWS output building, paging, apply-method mapping, storage limits and the gateway runnable check stay in the adapter path. The RDS agent declares its own EngineCatalog interface and types and receives an engine-backed implementation from cmd/rds-agent, so agent code does not import the catalogue. Cross-engine tests use the two real engines instead of a registered fake. * docs: record RDS engine catalogue owner move * test: characterize RDS DB parameter group lifecycle before extraction * docs: record RDS DB parameter group lifecycle contract * refactor: extract RDS DB parameter group owner Move the parameter group and override records, keys and listing into domains/rds/parametergroup behind an Owner. Delete asks an owner-declared Dependants interface; instance-side resolution reads through its own parameterGroupValues interface. SetOverrides refuses an unknown group so no override key is written without its group. Stored shape, keys, public errors and propagation are unchanged. * docs: record RDS DB parameter group owner extraction * test: characterize EKS add-on lifecycle and guest wire Pin the persisted record and manifest layout, create/update/delete and status-report transitions, the ignored client token and report version, the missing serviceAccountRoleArn PassRole check, and the exact internal add-ons HTTP body and agent TSV output as they stand today. * docs: record EKS add-on lifecycle contract * fix: require iam:PassRole for EKS add-on service account role CreateAddon and UpdateAddon now pass serviceAccountRoleArn through the existing EKS PassedRoleARNs path, so the caller needs iam:PassRole on the role for eks.amazonaws.com, matching CreateCluster and CreateNodegroup. * docs: record EKS add-on PassRole check * refactor: extract EKS add-on owner Move the add-on catalogue, record and manifest keys, CAS, status transitions and staging into domains/eks/addon behind an Owner that is the sole writer. The handler keeps AWS validation, error mapping and projection; the cluster reconciler delegates reports through the narrow addonReports interface; node groups call EnsureGPUDevicePlugin. Stored keys, JSON shape, wire types and lifecycle behaviour are unchanged. * docs: record EKS add-on owner extraction * refactor: extract EKS add-on guest wire contract Move the add-on status subject, delivery phase, status report, staged manifest and internal add-ons response into contracts/eks/v1 and use it from the handler, gateway and gatewayfetch, replacing the agent's duplicate. Wire bytes are unchanged, including the internal add-ons body that the SDK renderer emits with Go field names; compatibility tests pin the JSON, the guest printf form and the TSV. * docs: record EKS add-on wire contract extraction * docs: update EKS add-on inventory and remaining edges * docs: draft EKS add-on lifecycle correction design for review * chore: run contracts tests in the default test, coverage and race targets * docs: apply review decisions to EKS add-on lifecycle design * test: characterize EKS add-on v1 compatibility with added fields Pin which owner writes drop unknown record and manifest fields, that reads and deletes ignore or erase them, that one undecodable entry fails a listing, and that v1 wire consumers ignore extra fields. * docs: add EKS add-on executor, bundle, v1 compatibility and release inventories * docs: draft EKS add-on v2 guest contract design for review * docs: qualify historical architecture references * docs: apply review decisions and ADR-0006 to EKS add-on v2 design * fix(eks): bind internal report publishing to the caller's cluster PublishInternal was authorised by IAM policy alone, with its resource built from the body accountId and the URL cluster. The control-plane role grants it on "*", so any control-plane VM session, any tenant holding eks:*, or static system credentials could publish cluster state, bootstrap and add-on reports for another cluster or account. PublishInternal now passes the existing internal-route gate: the caller must be a control-plane instance-role session that is a member of the URL cluster in the body account. The gate and the handler decode the body through one shared decoder, so the account checked is the account the subject is built from. Every unauthorised target returns the same AccessDenied, and invalid account or cluster names are treated as not found. Valid publishes keep their subjects and payload bytes. * fix(eks): bind webhook token review to the caller's cluster WebhookTokenReview took its account from the request body and was authorised by IAM policy alone, with the control-plane role granting it on "*". A control-plane VM, any tenant holding eks:*, or static system credentials could resolve a token against another cluster or account and learn the Kubernetes groups it maps to there. Error responses also distinguished absent accounts from absent clusters. WebhookTokenReview now passes the same internal-route gate as PublishInternal: a control-plane instance-role session that is a member of the URL cluster in the body account. The gate and the handler share one body decoder, each body-scoped internal route must declare its reader, and every unauthorised target returns the same AccessDenied without reaching STS verification. Same-cluster responses are unchanged. * fix(eks): validate add-on serviceAccountRoleArn syntax CreateAddon and UpdateAddon stored serviceAccountRoleArn without checking it was an ARN, and the guest renders the value into the add-on's manifests. A non-empty value must now be syntactically an IAM role ARN (12-digit account, no region, role resource, IAM name and path rules); anything else returns InvalidParameterException before any record is written or manifest staged. The syntax check is foundation/aws/arn.ValidateRoleARN. iam:PassRole at the gateway remains the permission and existence check. Stored values are not rewritten, and an UpdateAddon that omits the field still succeeds on a record holding a legacy value. * docs: record EKS internal-route and role-ARN security corrections * docs: add EKS add-on release membership and activation case study * fix: point UI build, CI and lint rules at moved package paths * docs: record EKS add-on activation review decisions * refactor: move quota admission to domains/admission/quota Relocate the quota service, live counters and vCPU records from handlers/quota to domains/admission/quota. Package renamed from handlers_quota to quota; callers with a local quota identifier import it as admissionquota. KV buckets, subjects and error codes are unchanged, and the package's existing debt edges move with it unchanged. * docs: reconcile package-boundary record for ADR-0001 close-out Add the missing slice rows (the commits that dissolved spinifex/types, the ECR repository projection, the stale-path fix and the quota move), correct stale entries, record the dependency-rule breaks found in the import graph with removal conditions, add the close-out table of remaining legacy paths with their decided target owners, recount the mulga-side follow-ups, and fix stale old-path references in docs and comments. * test: move KV migration engine tests to foundation/state/migrate The Registry and RunKV tests exercise foundation/state/migrate exclusively but lived in spinifex/migrate's test file. Relocate them, with their NATS helpers, to the package that owns the engine. No test name, assertion or behaviour changes. * refactor: move config and object-store upgrade workflow to operator/upgrade Relocate spinifex/migrate, the operator-driven config-file and object-store upgrade workflow behind spx admin upgrade, to operator/upgrade. Package renamed to upgrade (imported as opupgrade where a local upgrade identifier exists). It stays distinct from foundation/state/migrate, the generic KV migration engine; no registry types, migration names, versions, file formats or command names change. * docs: record migrate move to operator/upgrade * test: enforce ADR-0001 layering with a blocking ratchet Add spinifex/architecture/layering, a test-only package that parses the module's import graph, maps every production package to an ADR-0001 layer and checks each dependency rule as its own subtest. Existing violations are allow-listed against their recorded debt; a new forbidden edge, an unmapped package, a stale allowlist entry or a new package under a frozen legacy root fails local preflight and CI. Record the nine edges the test found missing from the migration record (quota -> EC2 instance types, STS/Ochre/ELBv2 -> IAM, ELBv2 cross-domain, installer UI -> admin), name the importers of the utils residuals and gateway/ec2_idempotency.go, and correct the handlers/iam consumer list. * refactor: drop the legacy handlers_ecr import alias Import domains/ecr under its package name, or as ecrdomain where the file also imports the AWS SDK ecr package, matching acmdomain. Also fix a stale daemon file reference in the integration ECR daemon comment. * chore: mark spf13/pflag as a direct dependency operator/cli/wiring.go imports pflag directly. Same version; no upgrade. * docs: record test-package-check and nilaway as unverified gates * refactor: move the layering test to module-root architecture/ The ADR-0001 layering ratchet is repository governance tooling, not Spinifex product code, so it sits beside tests/ rather than under the spinifex/ product tree. make test, test-cover and test-race now include ./architecture/..., and the graph walk excludes architecture/. * fix: update paths left stale by the package moves The MariaDB image stamp test read the RDS engine from handlers/rds/engine_mariadb.go, so test-images failed in CI; it now reads domains/rds/engine/mariadb.go. Comments citing moved files now name their new locations. * refactor: move the default-VPC subject into contracts/ec2/v1 utils.SubjectEnsureDefaultVpc becomes ec2v1.EnsureDefaultVpcSubject, the request/reply route between gateway account creation and the daemon. Only the subject moves; the request and reply bodies are still anonymous structs on each side and are recorded as such in the contract README. The layering freeze now allows two utils files. * docs: qualify the migrate split and record admin and Viperblock findings The migrate row is a split, not an exact ADR-0001 map row, and needs a map clarification. Correct the stale admin consumers, record the operator-only admin files as movable, the vbwire prerequisite for the Viperblock adapter and the capability decision encryption.go needs. * refactor: move operator-only admin code to operator/admin Config generation, certificate issuance, host discovery, telemetry, email validation and image import/removal/orphan-volume tooling move to operator/admin. Legacy admin keeps only the symbols with non-operator consumers: default account identifiers, AWS credential generators and system image promotion. foundation/pki and the tenant ACM CA are unchanged. The readAMI helper and the removal test fixtures are duplicated privately in legacy admin rather than shared across the split. The now-stale operator/installer/ui -> admin layering allowlist entry is removed. * docs: record operator/admin split in package-boundary migration * test: pin viperblockd fence, abandon and dirty-marker wire shapes Characterization tests against the current vbwire package, before it moves to contracts/viperblockd/legacy/v1: both subject forms for the fenced and abandon routes, golden JSON for VolumeFencedEvent, VolumeAbandonRequest, VolumeAbandonResponse and DirtyRecord, the dirty bucket name, and the volume-key pattern shared by the lease and dirty stores. * refactor: move viperblockd fence, abandon and dirty-marker vocabulary to contracts Move the fence and abandon subjects/DTOs, the dirty bucket name, DirtyRecord and the shared volume-key pattern out of vbwire and into contracts/viperblockd/legacy/v1, alongside the package's existing mount/unmount/delete/sync/config-update routes. vbwire keeps only the I/O helpers (BindDirtyBucket, ListUnsealedVolumes), now built on the contract vocabulary instead of defining it. Record the approved dirty-marker ownership boundary in the contract README: the Viperblock adapter is the sole producer, viperblockd was only its transitional custodian. Document the fence and abandon routes and the dirty bucket in docs/service-interfaces.yaml. * refactor: split the Viperblock EBS adapter out of services/viperblockd Move the EBS provider adapter (volume lease, fence, dirty marker, nbdkit recovery, provider handlers, encryption key loading) to providers/ebs/viperblock. services/viperblockd keeps only process lifecycle and the NATS subscription wiring that starts and stops it. The dirty-bucket read path moves to providers/ebs/viperblock/dirty as a read-only ListUnsealedVolumes capability; the adapter's write, clear and purge logic stays unexported in the adapter package. Delete services/viperblockd/vbwire now that its vocabulary lives in contracts/viperblockd/legacy/v1 and its I/O helpers live in dirty. Update operator/cli, the runtime service registry, qemunbdd's config comment and the integration test harness to the new import paths, and drop the now-stale architecture/layering allowlist and frozen-package entries for the deleted package. Behaviour, persisted keys and NATS subjects are unchanged. * refactor: move the viperblockd role to runtime/roles/viperblockd With the EBS adapter in providers/ebs/viperblock, services/viperblockd holds only role supervision and the opt-in live data-path tests, so it joins the other runtime roles. It was the last package under services/; the frozen legacy list drops it. * docs: record viperblockd contract, adapter and role moves * test: characterise vpc.* network-realisation routes Pin every vpc.* subject, JSON payload shape and the request/reply {success,error} ack envelope exactly as they exist today, ahead of introducing contracts/network/v1. Covers the 22 subjects registered by domains/network/subscribers, the vpc.igw-attach/detach subjects and InternetGatewayEvent already owned by contracts/ec2/v1, the utils.AddNAT/PublishNATEvent client wire behaviour including the delete-nat retry-on-ErrNoResponders budget, and the EC2-side NATEvent and SGEvent/SGRule duplicates in domains/ec2/vpc. Also adds the six vpc.* route-table and system-egress subjects that were missing from service-interfaces.yaml despite being live production routes (vpc.add/delete-igw-route, vpc.gate/ungate-subnet- egress, vpc.add/delete-system-egress). * feat: add contracts/network/v1 for vpc.* realisation routes Declare the versioned wire vocabulary for the vpc.* control-plane-to- network-realisation boundary: subjects, payload types, the shared {success,error} ack envelope and the vpcd-workers queue group, one file per route family. No NATS I/O, no consumer switched over yet; the package coexists with the fragmented originals pinned in the prior characterization commit until slice 3 migrates call sites. * refactor: use contracts/network/v1 for vpc.* producers and consumers Switch every vpc.* producer (domains/ec2/vpc, eip, instance, natgw, routetable, igw, handlers/elbv2, handlers/eks, daemon, systemvpc) and the network/subscribers consumer onto contracts/network/v1 subjects, event types and the shared AckEnvelope. contracts/network/v1 becomes the sole owner of vpc.igw-attach/detach, replacing the duplicate definitions in contracts/ec2/v1. Deletes the duplicated local subject constants and event structs: subscribers' Topic* consts and event structs, vpc.NATEvent and SGEvent, eip's natEvent, natgw's natGatewayEvent, and eks's systemEgressEvent. domains/ec2/vpc.SGRule survives because EC2 persists it directly in SecurityGroupRecord; contracts/network/v1.SecurityGroupRule was expanded in slice 2 to match it field-for-field so wire bytes are unchanged. No lifecycle or reliability changes: the NAT add barrier, delete retry-on-ErrNoResponders, and the inconsistent per-call-site NAT delivery modes (EIP AssociateAddress and DeleteNetworkInterface both stay fire-and-forget with no ack) are preserved exactly, as are the golden wire literals pinned in the characterization tests. * refactor: replace utils/vpcd_event.go with a typed network projection client Every vpc.* call site now goes through domains/network/projection's operation-specific methods instead of utils.AddNAT, utils.PublishNATEvent or utils.RequestEvent, so no caller passes a bare subject string. Each method states today's delivery mode by name: AddNAT stays strict, AddNATBestEffort and AnnounceNATAdd/AnnounceNATDelete keep the gaps those call sites already had, and RemoveNAT keeps the ErrNoResponders retry. utils/vpcd_event.go and its tests are deleted; the behaviour they pinned (wire shape, ack envelope, retry-on-no-responders) moved into the projection package's own golden and nat tests, unchanged. utils/ now holds only encryption.go, which this does not touch. * refactor: route the remaining fire-and-forget vpc.* producers through projection CreateVPC/DeleteVPC, CreateSubnet/DeleteSubnet, AttachInternetGateway/ DetachInternetGateway, AddNATGateway/RemoveNATGateway, AddIGWRoute/ RemoveIGWRoute, GateSubnetEgress/UngateSubnetEgress and RemoveSystemEgress were still publishing through natsmsg.PublishEvent or a raw nc.Publish call with a bare subject string, left over from the mechanical slice 3 pass. Each now goes through its named projection.Client method instead, so every vpc.* producer in the tree uses the typed client. * refactor: move EBS encryption posture to domains/ec2/ebs/encryption and delete utils The master-key loader was used only by EC2 image, instance and volume to derive the AWS-visible Encrypted flag. It becomes ebsencryption.Enabled, EC2's temporary reading of the provider's key-file setting; the cache, empty-path meaning, error text and each caller's error handling are unchanged (image still reports unencrypted when the key will not load). Its successor is a providers/ebs capability reporting volume encryption posture. utils/ is now empty and deleted. The layering test drops utils and services from the legacy roots, removes their allowlist entries and fails if either retired root regains files. The S7 subject scan follows the vpc.* literals from utils to contracts/network so its gap list stays complete. * docs: record the network contract, projection client and utils removal * test: characterise instance-state persistence, recovery and generation handling Pin the current local-file bytes and schema failure modes, the instance bucket configuration, record key and wire form, the bucket version gate, generation preservation across every KV writer and the VM conversion, and what a returning node does for a missing, foreign, terminal or unreadable canonical record. These describe current behaviour, not the ADR-0007 target. * test: freeze direct instance-state consumers Add an AST ratchet over production code that fails when a new file names the daemon's instance-state bucket, record keys, local-file API, the raw vm.InstanceRecord or its conversion, or a JetStreamManager instance-state method. Today's 73 uses form a shrink-only allowlist keyed to the slice 0 inventory; stale entries fail, and a synthetic-source self-test proves the matcher detects each kind of use and ignores declarations. * docs: record ADR-0007 slice 0 instance-state inventory Record the instance-state persistence formats, the nineteen direct consumers by process and access kind, the characterised recovery and schema outcomes, the generation-preservation matrix and the ratchet that freezes the consumer set. Nothing conforms to ADR-0007 yet and vpcd stays blocked. * test: narrow the instance-state ratchet to instance-state access Stop freezing the JetStreamManager type and constructor, which also serve cluster state; flag only instance-state methods, bucket and key identifiers, record codecs and local-state access. The cluster-state-only consumers in daemon_mgmt_ip.go and operator/cli/cluster.go leave the allowlist (73 to 67). The self-test now proves a cluster-state use is ignored and an instance-state method call is caught. Record the owner's disposition of the KV-unavailable restore result in the migration record. * docs: record the narrowed instance-state ratchet commit * docs: design the instance-state transition record and activation gate * docs: record the instance-state transition-record design commit * docs: record slice 1a activation-gate decisions * feat: add instance transition-record codec with format marker Adds DecodeTransitionRecord and TransitionRecord.Encode in the record's owner package. A top-level format member selects the shape: absent or 1 decodes the legacy record and is never given a marker on write; 2 also decodes the new assignment and observation sections; an integer above 2 decodes its legacy fields read-only and Encode refuses it; anything else is refused on decode. Encode applies only the typed paths that differ from the decode-time snapshot onto the input, so unknown members at every object level and unchanged known fields keep their read form. A changed array is replaced whole. Decode refuses malformed JSON, duplicate keys at any depth, keys that alias a known field by case, trailing data and a non-object record, each with its own sentinel. No production reader or writer uses the codec yet; the new types are not part of vm.InstanceRecord, so every existing record encodes unchanged. The codec file is registered as an owner file of the instance-state ratchet. * docs: record slice 1b step 1 codec and awsgw rollout qualification Records the codec added in e62f921d2 as design Section 10 (C1 to C7): its surface, preservation at every object level, the changed-array limitation, marker handling, the rejection classes and its capable-writers-only scope. C2 supersedes P1's top-level-only preservation for the codec. G19 records that old read-only gateway consumers remain safe but DescribeInstanceStatus gains unconfirmed/degraded visibility only after awsgw upgrades. The migration record gains the commit row and states that no production path uses the codec yet. * refactor: move the instance transition-record codec to domains/ec2/instance/state The codec defines how the canonical persisted instance record evolves, with its assignment and observation sections, which is EC2 instance ownership rather than node-local VM supervision. It moves unchanged into its own package and keeps wrapping the legacy vm.InstanceRecord alias and its spec and status types, which stay in runtime/compute/vm for now. The domain-to-runtime import is recorded as new dependency-rule debt with its removal condition and allow-listed against that entry. The instance-state ratchet now names the new file as an owner file; its allowlist is unchanged. * fix: refuse array changes that would drop element extensions A changed array is replaced whole by the writer's value, which silently lost any member a newer writer had added inside its elements. Encode now inspects the array as read: if any element carries a member its typed schema does not know, at any depth, it returns ErrRecordExtensionConflict naming the array and the first such member. Arrays without such members are still replaced whole, unchanged arrays are still kept verbatim, and arrays inside unknown members are never inspected. * docs: record the codec move and the array extension-conflict rule Records 8db9771fb and c617914a1. T1 and Section 10 now name domains/ec2/instance/state as the eventual owner of the persisted instance record and its evolution, with vm.InstanceRecord as the temporary legacy type it wraps. C3 replaces the changed-array limitation with the refusal: a changed array with element extensions fails with ErrRecordExtensionConflict and is never silently dropped. P2 stays a conservative rule until finalisation. * fix: refuse removals that would drop record extension fields A capable writer may no longer remove or replace a known object, map entry or array when its stored value carries members the writer's schema does not know. The check that guarded changed arrays now runs wherever the merge drops or overwrites a stored value instead of merging into it: a known member deleted or set to null, a map entry removed or stored under a key the typed decode rewrote, a value of another JSON kind, and a changed array. Encode returns ErrRecordExtensionConflict naming the changed container and the first unknown member. Removal stays allowed when the stored value has no extensions, and a change merged member by member still keeps unknown members. * docs: record the uniform extension-conflict rule Adds design clause C8 for 0d7b4266d: a capable writer may not remove or replace a known object, map entry or array whose stored value carries unknown structured extension fields; removal without extensions stays allowed. C3 and C5 point at it. The migration record gains the commit row, updated subsection wording and a pointer-bump follow-up deferring make docs-portal to the Mulga gitlink PR so the portal evaluates the proposed Spinifex revision. * refactor: inject vpcd's IMDS instance-state readers from the instance state boundary * docs: cite the vpcd reader injection commit in the migration record * refactor: move vpcd to runtime/roles/vpcd * docs: cite the vpcd move commit in the migration record * refactor: move the ECS agent wire vocabulary to contracts/ecs/v1 Move handlers/ecs/bus to contracts/ecs/v1 (package ecsv1) with no legacy shim. Subject strings, JSON fields and types are byte-identical; the old-agent compatibility test moves unchanged and golden pins cover the remaining message types. The README route table records that only service-reconcile has a live producer today; the agent reuses these payload types through the gateway actions. service-interfaces.yaml lists ecs.bus.* under the daemon. * refactor: move system-image promotion to domains/ec2/image Move images_promote.go and its tests from admin to domains/ec2/image: SystemOwnerAlias, PromoteImageOpts/PromoteImageResult, PromoteSystemImage, GetAMIMetadata and the private snapshot reader. Storage, ordering, errors and promotion behaviour are unchanged; the daemon, gateway/spx and operator CLI callers import ec2image. admin now holds only account IDs and key generators. * docs: record the ECS contract and image-promotion moves and the remaining-roots matrix * refactor: move the bootstrap account identifiers to foundation/aws/identifiers DefaultAccountID and DefaultAccountName join GlobalAccountID as the fixed, platform-reserved identity of the first human-facing bootstrap account. Names and values are unchanged and stay fixed. Callers in daemon, gateway, awsgw, accountteardown and the operator CLI use awsidentifiers; admin now holds only the IAM credential generators. * docs: cite the bootstrap account identifier move in the migration record * refactor: inject the STS cluster JWKS lookup from handlers/eks handlers/sts declares ClusterJWKSResolver and keeps JWKS decoding and InvalidIdentityToken mapping; handlers/eks implements it as OIDCJWKSReader beside the bucket and key layout helpers. awsgw and the integration harness inject the reader. STS no longer imports any EKS package, including tests, and the handlers/sts -> handlers/eks layering exception is removed. * docs: cite the STS JWKS resolver cut in the migration record * refactor: move the AWS credential-format generators to foundation/aws/credentials and retire admin GenerateAWSAccessKey and GenerateAWSSecretKey move unchanged to foundation/aws/credentials as a stateless format primitive. handlers/iam and operator/cli import it directly. The admin legacy root is deleted and joins the retired roots so it cannot return. * docs: cite the admin retirement in the migration record * revert: remove the uncalled ADR-0007 codec and design stack from the ADR-0001 checkpoint The instance transition-record codec, its tests and the slice 1a design had no production caller. They leave this package-boundary checkpoint and will be reapplied on a dedicated ADR-0007 branch. Slice 0 characterisation and the vpcd IMDS readers in domains/ec2/instance/state stay. * docs: cite the ADR-0007 codec revert in the migration record * fix: declare the ECS action subjects in service-interfaces.yaml Declaring ecs.bus.* made ecs a managed prefix for manifest-lint, which then failed on the 34 ECS action subjects the daemon registers. Declare them as ecs.*, the same wildcard convention as rds.*. * chore: run manifest-check and manifest-lint in preflight CI runs both, but preflight did not, so manifest drift could pass local checks and still fail Build and Test. * docs: record resumed preflight enforcement and dev merge ports * fix: restore dev changes dropped by earlier merges Reapplies the slices.ContainsFunc rewrite in nodeFitsCustomerInstance and the DeleteDBSubnetGroup doc comment, both lost when their files were refactored. * docs: record accountteardown as a frozen legacy root pending cleanup capabilities --------- Co-authored-by: Julian Sommer <115516918+juliansommer@users.noreply.github.com>	2026-10-15 14:42:53 +10:00
Josh Siviour	98ec781629	feat: decouple the EC2 control plane from the viperblock engine behind an EBSProvider contract (#770) ... * feat: introduce the EBSProvider interface and control-plane metadata store Phase 1 of decoupling the control plane from viperblock. Adds a provider-neutral block-storage contract that spinifex owns end to end. ebsprovider defines EBSProvider, whose operation set and idempotency rules follow the CSI controller service, with NATS request/reply as the transport rather than CSI's gRPC. Every request and response carries an explicit schema version so wire skew fails loudly at the boundary instead of silently decoding a changed payload. The package deliberately exposes no viperblock types: provider-specific state is an opaque handle. Ships with a NATS client against the ebs.provider.v1.* subjects and an in-memory fake for tests. ebsmetadata gives spinifex its own volume and AMI documents under a spinifex key prefix, so the control plane can answer DescribeVolumes and DescribeImages without reading the storage engine's persisted state. The EC2 volume and snapshot handlers gain provider-backed paths for create, describe, modify, attach-state and delete. Provider injection is optional for now, so the existing engine path stays the default until the viperblockd side serves the new subjects and the metadata migration lands. vm/lifecycle.go no longer imports viperblock; FindFreePort was the only symbol it used and is now a local helper. * feat: serve the EBS provider contract from viperblockd Gives the ebsprovider NATS client a server. Volume create, describe, expand and delete, plus snapshot create and delete, are now handled by the daemon that owns BaseDir and the mounted-volume registry, which is where viperblock engine construction belongs. Every handler prefers an already-mounted engine over opening a second one on the same volume, and expand refuses outright while the volume is mounted. Opening a second engine on a live volume is the double-writer hazard this decoupling exists to remove, so the boundary enforces it rather than trusting callers. Requests carrying an unrecognised schema version are rejected at the boundary instead of being decoded on a best-effort basis. Snapshot creation replies immediately with an operation ID and completes asynchronously on a per-snapshot subject, since a large volume will outrun the request timeout. Draining the volume stays with the caller: it coordinates with the guest and is not something the storage boundary can reach. The snapshot create subject gains an explicit create verb. Addressing it as ebs.provider.v1.snapshot.<volumeID> collided with the snapshot delete subject and left the wildcard unsubscribable. Publish and unpublish are not served yet; the mount and unmount logic they would front is still inline in launchService and needs extracting first. Also adds a conformance suite that runs one set of contract assertions against both the in-memory fake and the NATS client, so each side is checked against the contract rather than against the other's structs. * feat: let an operator select the EBS provider Adds an [ebs] provider key and wires the NATS provider into the EC2 volume, snapshot, image and instance services at the daemon's composition root. Until now nothing injected a provider, so the provider-backed code paths in those services were unreachable. The key is provider-neutral rather than nested under [viperblock], because it names the boundary rather than one provider's settings; a second provider will not need it renamed. An empty value resolves to "embedded", so deployed config files that predate the key keep today's behaviour, and an unrecognised value is a startup error rather than a silent fallback. Startup probes the provider's capability verb and warns when nothing answers. The daemon and viperblockd start independently, so an unanswered probe is not fatal, but without it a misconfigured node fails much later as an unexplained request timeout on the first EBS call. "viperblockd" stays experimental: under it volume metadata lives in the control plane's own document, and the leak reaper, GC and admin paths still read viperblock's config.json, so they cannot see tenant or tag data for volumes created that way. * fix: make every volume-metadata consumer provider-aware Several readers and writers of volume metadata were never given a provider branch, so under the viperblockd provider they silently used the wrong store. Each of these is a correctness bug rather than a missing feature, because the control plane had already stopped writing the document they read. Modifications had nowhere to live: ModifyVolume built its result in memory and dropped it, and DescribeVolumesModifications read it back out of viperblock's config.json, so a describe straight after a successful modify returned nothing. Volume metadata now carries its own modification record. The leak reaper read attachment and tags from config.json and wrote orphan markers to tags.json, neither of which exists for a provider-managed volume, so a leaked volume was invisible to it and any mark it did write could not be read back. Tag mutations had the same split: a tag applied after creation never reached the document DescribeVolumes reads. Snapshot deletion could not see a provider-managed clone, because a clone records its source only in the control-plane document. That let a delete strip chunks a live clone still reads, so it is fixed here rather than left for the migration. Volume enumeration and DescribeVolumeStatus were likewise scanning object prefixes that a provider-managed volume does not create. Also adds an encryption flag to the volume document, which DescribeVolumes had been reporting as false unconditionally and snapshots could not carry at all, and a list operation for AMIs so the image path can follow later. The legacy path is unchanged; its invariant tests pass unmodified. * feat: backfill ebsmetadata documents from legacy volume and AMI state DescribeVolumes under the viperblockd provider enumerates only ebsmetadata documents, so a volume created before the switch had no document and was invisible rather than merely slow to read. A per-object read fallback cannot fix enumeration, so both a backfill and a fallback are needed. Add an object-store migration kind to the migrate framework. Predastore has no conditional write, so an object-based version stamp would be last-writer-wins across nodes; RunObject stamps progress in a caller-supplied JetStream KV bucket instead, exactly as RunKV stamps a bucket's own version. The stamp is a read-then-write rather than a compare-and-swap, so correctness rests on every ObjectMigration.Run being safe to re-execute. The backfill itself lives in migrate/ebsmetadatabackfill rather than beside the numbered config migrations: it needs viperblock's VBState schema to decode the legacy config.json, and migrate is imported by every handler that stamps a KV bucket version. It converts what it can reach and skips unreadable objects with a log, so one corrupt volume cannot hide the rest of the fleet. ebsmetadata gains the legacy read fallback for the window before the migration has run everywhere. It stays free of viperblock by taking the decode as an injected function value, wired at the composition root, and the fallback is retired by leaving it unset. A fallback read never writes the converted value back, which would race the migration. Prefix enumeration pages to exhaustion. Stopping at the first page would let the backfill stamp itself complete having converted only the volumes it happened to see, reintroducing the invisible-volume failure it exists to prevent. The migration runs from configureEBSProvider, so only when the provider is selected; backfilling while the embedded engine is still authoritative would produce documents that immediately go stale. Failure is fatal rather than advisory, unlike the capability probe beside it. This makes the switch to viperblockd one-way, which is now recorded on the config field. * feat: serve volume publish and unpublish from viperblockd PublishVolume and UnpublishVolume were the last unserved verbs on the provider contract, and they are the ones that attach a volume to a VM. Until they are served the provider path cannot boot an instance, so provider = "viperblockd" cannot be verified end to end. The mount and unmount logic was two large anonymous handler bodies inline in launchService. Rather than write a second mount path, extract each into a named function and have both the legacy ebs.mount/ebs.unmount handlers and the new provider handlers call it. Two divergent implementations of nbdkit spawning and the seal decision would be far worse than the inline bodies. The extraction relocates code without rewriting it; response publishing stays in each handler so the provider never publishes to ebs.mount.response. Publish is idempotent: a volume this node already has mounted returns its existing attachment rather than starting a second nbdkit against it, which is the double-writer hazard the boundary exists to prevent. Unpublish preserves the invariant that a failed seal leaves the volume mounted so a retry can re-attempt it, and reports an error rather than success. Both verbs are node-addressed, so they subscribe directly rather than through the spinifex-workers queue group, and are registered only when NodeName is set. There is no queue-group fallback: a subject that already names one node has nothing sensible to fall back to. Read-only attachment is refused rather than silently granted read-write, since nbdkit is started read-write or not at all. Also fixes a latent panic carried by the extracted mount path: viperblock.New returns a nil VB alongside its error, and SetCacheSize was called on it before the error was checked, so a failing New would have taken down the handler. * feat: read and write AMI metadata through ebsmetadata The backfill migration wrote ebsmetadata AMI documents that nothing read: every AMI path still went through viperblock.AMIMetadata inside a VBState wrapper at {imageID}/config.json. Give the image service provider branches for the AMI read, write and enumerate paths, with enumeration going through ListAMIs rather than an object-prefix scan, as DescribeVolumes already does. AMIMetaLoader declared GetAMIConfig returning viperblock.AMIMetadata, putting a viperblock type on an interface boundary in the instance package. It now returns ebsmetadata.AMI on both paths, the embedded one converting before it returns, so the boundary names no viperblock type whichever provider is selected. The legacy-to-document mapping had accumulated three copies. Consolidate them in ebsmetadata/vblegacy, a sibling package rather than a member so ebsmetadata itself stays free of viperblock, and cover it with a reflective test that fails when a field is added to either schema without being wired through. Sixteen fields copied by hand in three places would have dropped one silently. The admin image paths read whichever representation exists and write back to that same one, so a provider-managed AMI never gains a spurious config.json. FindAMIDependents now unions ebsmetadata volumes with the legacy prefix scan: missing a dependent there deletes an AMI a live volume still needs, the same class of bug as the snapshot clone path fixed earlier on this branch. That union is built by hand rather than by wiring Store.ListVolumes' fallback, which swallows per-ID read errors. This path deliberately fails closed on a transport error so a delete cannot proceed on a partial picture, and the fallback would have quietly turned that into failing open. The CLI image import now also writes the document, best-effort, so an AMI imported after the migration is not left reachable only through the fallback. * fix(ec2): resolve volume config through ebsmetadata when a provider is configured A provider-created volume has no vol-*/config.json — its metadata lives in the ebsmetadata document. getBaseVolumeConfigAndEncryption read the legacy key unconditionally, so AttachVolume reported a volume that DescribeVolumes had just listed as available as InvalidVolume.NotFound. Routing through ebsmetadata.Store also puts this path behind the legacy fallback, so a volume created before the provider switch stays attachable. The NoSuchKey remap now names the key it missed; its silence made the original failure invisible in the daemon logs on every node. * test(bench): add an EC2 control-plane latency benchmark Measures the EBS control-plane operations either side of the provider boundary, so the cost of the NATS hop can be stated rather than guessed. Reports median and p95 with a bootstrap CI on the median difference, and labels a delta indicative unless that CI excludes zero. * fix(ec2): drain the volume before a provider snapshot The legacy CreateSnapshot branch drains first so the snapshot reads a current checkpoint; the provider branch did not, and viperblockd documents the drain as the caller's responsibility. Both sides deferred to the other, so an attached volume snapshotted stale data with no error raised. DrainVolume and volumeAttachment now take the fallback state and instance as strings rather than a viperblock.VolumeMetadata, removing a viperblock type from an exported signature. * feat(ec2): route the instance root volume through the EBS provider RunInstances built its own viperblock engine to clone the AMI snapshot into the root volume, which made every launch a second writer against a volume viperblockd already serves. The launch now calls the provider's CreateVolume with the AMI's snapshot and source volume, and records the result in ebsmetadata so DescribeVolumes and attach can see it. A snapshot clone needs both the snapshot ID and its source volume ID to resolve base blocks, so CreateVolume in the volume handler now sends SourceVolumeID alongside SourceSnapshotID; without it the daemon rejected every create-volume --snapshot-id outright. The gp3 IOPS and throughput constants move to spinifex/types so the instance and volume handlers share one definition rather than duplicating literals. * feat(ebsprovider): add a bounded volume seed to CreateVolume The EFI variable store must be initialised from the launching node's firmware VARS template, byte for byte. Passing a host path would not work: CreateVolume is queue-subscribed, so any node can service it, and a foreign node's OVMF package would bind the guest's pflash region to the wrong firmware build. CreateVolumeRequest carries the bytes instead, as SeedData, and viperblockd writes them at offset 0 in the engine it already builds. The seed applies only when the create actually allocates the volume, so a relaunch never overwrites a BootOrder the guest has since written. JSON base64-encodes a []byte, inflating the payload by 4/3, so MaxSeedBytes bounds the seed well inside the NATS max_payload the cluster runs with and both ends reject an oversized seed with a clear error rather than letting the publish fail. VolumeSeeding advertises the behaviour so a provider that cannot seed says so instead of silently dropping the bytes. * feat(ec2): route the EFI variable store through the EBS provider prepareEFIVolume built a control-plane viperblock engine to seed the variable store from the firmware VARS template, making every UEFI launch a second writer against a volume viperblockd already serves. It now calls the provider's CreateVolume with the template as seed bytes, so the store is allocated and written by the daemon that owns the volume. The template is still read on the launching node and shipped with the request. CreateVolume is queue-subscribed, so any node can service it, and a VARS region seeded from a foreign node's OVMF build would bind the guest's pflash to the wrong firmware. pflash refuses a VARS region that is not byte-exact, so the returned capacity is checked against the template length; a provider that rounded up to a GiB boundary would otherwise yield a guest that cannot boot. The engine path stays behind a nil-provider guard until the legacy branch goes. * feat(ec2): route image snapshots through the EBS provider snapshotRunningVolume and snapshotStoppedVolume each built a control-plane viperblock engine to take the snapshot backing a new AMI, making CreateImage a second writer against a volume viperblockd already serves. Both now call the provider's CreateSnapshot with the volume's provider handle. The running path keeps its drain, which is what makes the snapshot current rather than one predating a guest-triggered write. The stopped path needs no drain, and the daemon already prefers a live mounted engine over opening a second one, so it handles both cases itself. getVolumeConfig read the legacy config.json, which a provider-created volume does not have, so every CreateImage against one failed. It now reads the ebsmetadata document under a provider, the same way attach does. * fix(daemon): only the owning node creates an image for a stopped instance handleEC2CreateImage is a fan-out. Ownership is established by vmMgr, which only the node holding the VM passes, so a running instance is imaged once. A stopped instance lives in the cluster-replicated KV instead, which every node reads successfully, so all of them ran the full snapshot and AMI creation. The caller saw the first reply and the rest leaked: on a three-node cluster one create-image produced three AMIs and three snapshots. A stopped instance records its owner in LastNode, so a node that is not the owner now declines. Gather tallies error frames and keeps waiting, returning only on a success, so declining cannot preempt the owner's reply. An instance stopped by a build that never set LastNode elects an owner through the KV's compare-and-swap, since having every node decline would make create-image fail permanently for those records. * perf(ec2): serve DescribeVolumes by ID from the volume documents The provider branch called ListVolumes unconditionally and filtered in memory, so asking for one volume read and decoded every volume document in the bucket. The non-provider branch already had the equivalent fast path. Explicit IDs now fetch their documents directly. The tenant check moves with them: a document belonging to another account reports not-found rather than being returned, matching what the enumeration filter did. Measured against a memory object store, the fast path stays flat near 20us regardless of bucket size while the enumeration grows linearly, reaching 4.6ms at 500 volumes. * chore(lint): ban the viperblock import from the EC2 control plane The control plane reaches block storage through ebsprovider now, but nothing stopped a handler from importing the engine again. That is not hypothetical: the instance handler first imported viperblock for a config struct alone, and the engine construction followed thirteen days later. depguard denies the import across handlers/, which matters because viperblock.New starts a chunk uploader — every construction is a writer against a volume viperblockd already serves. A types-only import is denied too, since that is exactly how the last one started. The four files still carrying the pre-provider engine path behind a nil-provider guard are exempted by name. The exemption list is the remaining work: it shrinks to nothing when that path goes. * fix(ec2): refuse CopySnapshot instead of creating an unusable snapshot CopySnapshot wrote a control-plane snapshot document under the new ID and nothing else. The copy described correctly and CreateVolume against it succeeded, so it looked like it worked, but the new ID had no viperblock snapshot metadata behind it and the volume failed when the guest attached it. Producing the metadata means re-sealing it under the destination ID. On an encrypted volume it is AEAD-sealed with the snapshot ID in the AAD and the sealing helpers are unexported, so spinifex cannot write it. Copying only the unencrypted form would be dead code on any cluster with encryption enabled. Refusing with UnsupportedOperation fails at the call the caller can act on rather than at attach time. Source lookup and the ownership check still run first, so a bad ID or another tenant's snapshot reports that instead. * test(ec2): give handler test fixtures their own legacy config.json shape Handler tests built the legacy config.json fixture by importing viperblock's VBState/VolumeConfig/VolumeMetadata/AMIMetadata directly. Mirror that shape in ebsmetadata/vblegacy, next to the production code that already reads it (ebsmetadatabackfill), and switch the fixture-only usages across the volume/snapshot/image handler tests to it. A byte-for-byte equivalence test against the real viperblock types guards the mirror from drifting out of sync. Call sites that hand a viperblock type into putVolumeConfig, mergeVolumeConfig, or buildVBConfig are untouched, since those functions still name the real type in their signature. * feat(ebsprovider): add CopySnapshot to the EBS provider contract Adds a CopySnapshot operation to EBSProvider (types, ebs.provider.v1.snapshot.copy NATS subject, MemoryProvider and NATSProvider implementations, conformance coverage) and a viperblockd handler that duplicates a snapshot's metadata via viperblock.CopySnapshotMeta on the source volume's VB. * feat(ec2): serve CopySnapshot through the EBS provider CopySnapshot has been refusing with UnsupportedOperation because a copy needs its own snapshot metadata on the backend under the new ID, and on an encrypted volume that metadata is AEAD-sealed with the snapshot ID in the AAD, so the control plane cannot re-seal it. The provider contract now carries a copy operation, so the storage engine does it. The provider path generates a new snapshot ID, has the provider duplicate the backend metadata under it, then writes the control-plane document. Rollback mirrors CreateSnapshot: a failure after the copy deletes the provider snapshot rather than leaving one nothing references. Ownership is still checked against the source before anything is created. The no-provider path keeps refusing. It has no way to produce the backend metadata, and the copy it used to write described fine and then failed at attach — a resource that fails as far as possible from the call that made it. Adds MemoryProvider.Snapshot so a control-plane test can assert a snapshot reached the provider rather than existing only as a control-plane document. That assertion is what catches the old behaviour. * refactor: remove the embedded EBS engine path from the EC2 control plane viperblockd is now the only EBS provider. The pre-provider path that constructed a viperblock engine in-process is deleted, and with it every github.com/mulgadc/viperblock import under spinifex/handlers/ (tests included). The depguard ec2-control-plane rule drops all four file exemptions and the !$test carve-out, so the rule now reads simply as "nothing under spinifex/handlers/** may import viperblock". viperblock.VolumeConfig was also a data carrier on the provider path. It is replaced by the spinifex-native ebsmetadata.Volume rather than the vblegacy mirror: vblegacy mirrors a legacy on-disk shape whose only job is decoding old objects, while ebsmetadata.Volume already carries every field the call sites read, so the conversion step disappears instead of being reimplemented against a legacy shape. The embedded-only helpers (volumeConfigWrapper, putVolumeConfig, mergeVolumeConfig, configIsEncrypted, putVolumeConfigViaDetached, deleteS3Prefix, buildVBConfig, snapshotVolume, the ami-*/config.json prefix scan) had exactly one production caller chain each, all through a nil-provider branch, and are removed. The snapshot-dependency guard on DeleteVolume is provider-agnostic and is kept, now running on the provider path where it previously did not. config: viperblockd is the default and an empty Provider resolves to it. An explicit provider = "embedded" is rejected at config load rather than silently upgraded, because starting anyway would migrate a node's volumes to ebsmetadata one-way without the operator asking. The generated spinifex.toml template emits viperblockd. * fix(images): write the imported AMI document from the config the import wrote ImportDiskImage creates the AMI's snapshot and records it on its own *viperblock.VB, which viperblock.New allocates fresh, so the value lands only in {imageID}/config.json. The import command was persisting the ebsmetadata document from its pre-import manifest copy, whose SnapshotID is still empty. Store.GetAMI only consults the legacy config.json fallback when the document is missing, so that empty-SnapshotID document permanently shadowed the real value and every launch from an imported AMI failed the zero-copy clone check with ServerInternal. Rebuild the document by reading back the config.json the import just wrote. A missing or unreadable config is skipped rather than written from the stale manifest: no document still resolves correctly through the legacy fallback. * test(e2e): read NODE from spx get vms instead of VCPU in the spread check spx get vms gained HEALTH and CRASHES columns, shifting NODE from field 6 to field 8. The spread placement check still read field 6, so every instance reported its vCPU count instead of its node, the unique-node count always collapsed to 1, and the check failed on clusters that had spread correctly. Read field 8 and strip the ANSI colour codes wrapping each cell. * feat(viperblockd): add a --debug flag so viperblock debug logging is reachable viperblockd hardcoded Info, and viperblock's VB.logger() falls back to slog.Default() because vb.log is only ever set by SetDebug. That left the engine's debug records, including the chunk uploader's start and disabled lines emitted during New(), unreachable in a deployed environment. Binds the namespaced viper key viperblock-debug and SPINIFEX_VIPERBLOCK_DEBUG rather than the bare debug key, which several commands share. Also sets the Config.Debug field, which existed but was set only by tests. * fix(viperblockd): release the chunk uploader when openVolumeVB fails viperblock.New starts a chunk uploader and a WAL syncer before the backend is touched, so a failure in Backend.Init or loadStateWithRetry returned nil to the caller while leaving both running with no handle to stop them. Repeated backend failures on CopySnapshot, ExpandVolume or DescribeVolume accumulated uploaders on a 30s ticker for the life of the process. Adds invariant tests for both halves of the ownership rule: a mounted volume's snapshot create and copy reuse the live engine and log zero volume opens, an unmounted volume opens exactly one, and a failed open leaves no uploader behind. The open counts are read from the same log record a production alarm watches. * fix(ebsprovider): route requests to the node that owns the mount Every viperblockd queue-subscribed the ebs.provider.v1.* verbs in one spinifex-workers group, so NATS delivered each request to a random node. Only the node holding the mount can reuse the live engine through findMountedVolume; any other node constructed a second viperblock engine, with a live 30s chunk uploader, against a volume nbdkit was serving on a different host. Measured on a three-node cluster, this was roughly two snapshots in three. Rather than resolve the owner, let the owner answer. A node subscribes ebs.provider.v1.owner.<volumeID>.<verb> as a plain subscription when it mounts a volume and drops it on unmount, mirroring the per-volume ebs.config subscription. Clients try that subject first and fall back to the queue group only on ErrNoResponders, which means nothing is mounted and opening an engine is correct. A timeout deliberately does not fall back, since the owner may still be running the operation. Applies to snapshot create and copy, expand and describe, the four verbs that reuse a mounted engine. Delete keeps queue dispatch. * fix: rebuild viperblockd mounted-volume registry after a restart Config.MountedVolumes is in-memory and rebuilt from nothing on start, so a viperblockd restart while a VM keeps running leaves nbdkit serving a volume the daemon has forgotten. Owner routing then infers from ErrNoResponders that nothing is mounted and falls back to the queue group, which opens a second viperblock engine, with a live chunk uploader, on another node. The same empty registry also defeats handlePublishVolume's double-mount guard, so a republish could start a second nbdkit. Discover surviving nbdkit processes from /proc at startup and rebuild the registry from them, following orphan_scan.go's precedent: match comm exactly, parse the argv for volume=<id> and --unix/-p, and adopt a PID only when nbdkit-vol-<volume>.pid names that same PID. Nothing is started, signalled or killed; anything that fails corroboration is logged and skipped. Recovery runs before the first subscription so no handler can race it. Extract mountVolume's engine construction into constructMountedVB so mount and recovery cannot drift, and release the WAL syncer viperblock.New starts when construction fails after it. * fix: corroborate recovered nbdkit processes from argv, not a pidfile nbdkit is launched with -f (required for the Go plugin) and never writes the --pidfile it is given, so no such file exists on any node; the daemon's own /tmp is a PrivateTmp namespace besides. Corroborating against it rejected every genuine mount, making recovery a no-op in production. Corroborate against what the kernel actually has: the process must serve our plugin, name this daemon's base dir, and still hold its socket. Adopt a volume once, so two live nbdkits for it leave one registry entry and a warning rather than two conflicting ones. * feat: add a second EBS provider backed by qcow2 and qemu-nbd The decoupling was justified by swappability that nothing demonstrated: the conformance suite ran against MemoryProvider and against a NATSProvider wired to a MemoryProvider, so both arms were the same implementation behind different transports. A fake is not a second implementation. Add three pieces. natsserve serves the ebs.provider.v1.* contract from any EBSProvider, depending on nothing but the interface, and replaces the test-only server twin so conformance now exercises production code. The conformance suite moves to its own package and is exported so implementations outside ebsprovider can run it, with no assertion changed. qemunbdd is the second implementation: one qcow2 file per volume, qemu-nbd for publish, real snapshot copies instead of chunk references, and every exec behind a runner seam so its tests need no qemu. Owner-subject routing is deliberately not served neutrally: it needs a per-node mounted-volume registry the interface does not model, so it stays in viperblockd and a neutral server's clients correctly fall back to the queue group. * test: run the conformance suite against the qcow2 provider The suite passes unmodified against an implementation sharing no code with viperblock, both in-process and through natsserve over the real wire contract, which is the swappability claim the provider boundary was built to support. Two real defects it caught. ExpandVolume and GetVolume inspected the image before consulting the publication map, so qemu-img could not open a volume qemu-nbd held the write lock on and the refusal surfaced as an internal error instead of ErrVolumeInUse; qemu-img info now runs with --force-share, so describing a volume no longer depends on whether it is attached. Publish also failed with qemu-nbd's raw exit status when the socket path exceeded the 108-byte AF_UNIX limit, and now reports that reason itself. * feat: make the EBS provider selectable by config Add the qemunbd selector alongside viperblockd, a spx service command that serves the qcow2 provider over natsserve, and service registration. Config validation accepts the new value everywhere viperblockd is accepted, while embedded stays rejected by name. The daemon logged a hard-coded viperblockd constant as the active provider rather than the resolved one, in configureEBSProvider and in both of probeEBSProvider's lines; all three now report what is actually configured. Both daemons answer the same subjects, so exactly one may run on a cluster. * test: add a live lifecycle check for the qcow2 provider Drives create, publish, write, snapshot, restore and read-back entirely through ebsprovider.NewNATSProvider against a real qemunbdd daemon on a cluster node, so the client under test is the same shape the control plane uses and never touches the provider type. Skipped unless SPINIFEX_QEMUNBD_LIVE is set, so it stays out of preflight. * fix: publish NBD URIs in the form standard clients accept PublishedVolume.NBDURI carried nbd:unix:/path, which is QEMU's legacy pre-URI filename syntax rather than an NBD URI. libnbd rejects it outright with "URI must begin with 'nbd://'", so no NBD client but QEMU could ever consume what the EBS provider boundary hands back. Emit nbd+unix:///?socket=/path instead, the form libnbd, qemu and nbdkit all accept. ParseNBDURI now takes both that and the TCP form, and still accepts the legacy nbd:unix: syntax for state written by older daemons, so a conformant third-party provider's URI is no longer rejected on the way in either. Verified against qemu 10.0.11: qemu-img and a real -drive option string both open the URI form, and qemu reports both forms as nbd+unix://?socket=, so it already treats the URI as canonical. * test: validate published exports with libnbd's client tools Every other assertion about the EBS provider goes through our own Go client, so nothing has ever checked whether the export we publish is usable by an NBD client that knows nothing about this codebase. That is the layer neither the conformance suite nor a CSI-shaped contract can reach. RunNBDClientSuite drives nbdinfo and nbdcopy against a published volume: the URI connects, the export advertises its size and block-size constraints, data written externally reads back byte for byte, a ReadOnly publish sets the read-only transmission flag, and UnpublishVolume tears the export down. It skips when libnbd-bin is absent rather than passing vacuously. Wired to qemunbdd, where all five failed before the URI fix. The publish assertion in the main suite now requires a dialable URI instead of merely a non-empty string, which is what let the wrong form through. * test: run the external NBD client suite against a live viperblockd The suite so far only ever saw qemu-nbd. Pointing it at viperblockd's nbdkit export is the comparison worth having: one external client, two providers it cannot tell apart, and every difference is a candidate leak in the boundary. RunNBDClientSuiteWithConfig takes the node name and volume prefix a live cluster needs, and publishForNBD now unpublishes and deletes what it created so a run against a real cluster leaves nothing behind. Subtests dial a normalised URI so a provider emitting the legacy syntax still gets its export tested rather than every subtest failing on the same string; whether the URI itself is standard is now its own subtest. Adds a reconnect check, since publication holds the volume rather than any one connection. It retries the real operation because a cheaper liveness probe is itself a connection and re-triggers whatever refused it. * feat: make the conformance suite capability-driven The suite asserted a fixed Capabilities literal, so it could only ever pass against a provider advertising exactly that set. Every implementation had to match the suite rather than the suite testing the contract. RunSuite now reads GetCapabilities from the provider under test and gates optional behaviour on what it advertises, and the fixed literal is demoted to ReferenceCapabilities, a convenience for callers constructing a MemoryProvider. Add ReadOnlyPublish to Capabilities. A provider that leaves it false must refuse a ReadOnly publish rather than hand back a writable export, which is what viperblockd already does; it now has a way to say so up front. Add ErrUnsupportedCapability and the unsupported_capability error code. A request for optional behaviour a provider does not advertise is well formed, so classifying it as invalid_argument told the caller to fix a request that was never wrong. viperblockd's ReadOnly refusal is reclassified accordingly. Declared capabilities now match observed behaviour: qemunbdd advertises SparseExtentReporting (qemu-nbd exports base:allocation, confirmed with nbdinfo) and ReadOnlyPublish (PublishVolume passes -r). viperblockd advertises neither: the nbdkit Go binding exposes no extents callback, and the mount path never passes -r. The external NBD client suite gains a sparse-extent subtest that checks the export's advertised contexts against the capability, so SparseExtentReporting is falsifiable from outside rather than taken on trust, and its read-only subtest now branches on the capability instead of assuming refusal. Cover the new branches with a MemoryProvider advertising no optional capabilities and one advertising OnlineExpansion, the branch no provider we ship exercises. * refactor: rename SourceVolumeID to SourceSnapshotVolumeID CreateVolumeRequest.SourceVolumeID meant three different things. viperblockd required it whenever SourceSnapshotID was set and used it to resolve the snapshot's chunk references, so there it named the snapshot's origin volume. MemoryProvider ignored it entirely. qemunbdd implemented it as an independent volume-to-volume clone, which is what the name and doc comment implied. The conformance suite could not catch the divergence because the reference provider had no branch for the field at all. The contract already has a field meaning "the volume this snapshot came from": Snapshot.SourceVolumeID, which every provider populates. So the request field is the same fact travelling back the other way, and its name was the problem. Rename it to SourceSnapshotVolumeID, document it as the source snapshot's origin volume, and state that it is required with SourceSnapshotID and meaningless without it. All three providers now enforce one rule: a source snapshot must be accompanied by its origin volume, or the request is invalid_argument. MemoryProvider additionally rejects an origin that does not match the snapshot's own SourceVolumeID, so a wrong name fails instead of resolving blocks against a volume the snapshot never came from. qemunbdd loses its volume-to-volume clone branch, which implemented behaviour the contract no longer offers and no caller ever requested. The suite pins both the requirement and a full create-snapshot-restore round trip, so the field is exercised end to end rather than only on the error path. * feat: make the conformance suite runnable against a live provider The suite had only ever run against MemoryProvider and qemunbdd, both of which are discarded with the test binary. viperblockd, the provider production actually uses, was the one implementation the suite never judged, because the suite assumed each subtest got fresh state: hard-coded volume IDs collide with an earlier run's leftovers on a store that keeps them, and a hard-coded node ID addresses a node that does not exist. SuiteConfig adds NamePrefix, NodeID and OtherNodeID. A tracking wrapper records every volume, snapshot and publication the suite creates and tears them down in dependency order, logging rather than failing so a teardown problem cannot mask the assertion a subtest was making. Two new tests cover this by running the whole suite twice against one shared provider instance, which passes only because cleanup works, and once per prefix to cover concurrent runs sharing a daemon. TestLive_ViperblockdConformance wires this to a real cluster behind SPINIFEX_VIPERBLOCK_LIVE, alongside the existing external NBD client suite. * fix(viperblockd): close the four contract gaps the live conformance run found Unpublishing a volume this node has no mount for now succeeds instead of returning not_found, matching the legacy unmount path: nothing mounted here is already the state the request asks for. CreateSnapshot refuses a snapshot ID that already exists against a different source volume with already_exists, rather than overwriting it. DeleteVolume refuses a published volume with volume_in_use instead of tearing the mount down, on this node or on whichever node answers the volume's owner subject. The export and the guest writing through it survive the metadata deletion, so the old behaviour surfaced later as corruption. CreateVolume reads the source snapshot before writing the volume, returning not_found when it is absent and invalid_argument when it was taken from a different volume than the request names. Previously both produced a blank volume and a successful response. CopySnapshot classifies viperblock's foreign-volume refusal as invalid_argument now that it carries a sentinel. * feat(ebsprovider): pin the source snapshot's origin volume in the contract The suite only required source_snapshot_volume_id to be present, so a caller naming a volume the snapshot never came from was accepted everywhere. The snapshot records its own origin, so this is checkable: creating from a snapshot with a mismatched source volume is now invalid_argument for every provider, enforced by qemunbdd against its snapshot metadata and by viperblockd against the snapshot's persisted SourceVolumeName. * test(ebsprovider): run the contract suite against viperblockd in CI CI installed neither qemu nor nbdkit, so every conformance test that needs a real implementation skipped silently and MemoryProvider was the only provider the suite judged. CI now installs both, builds viperblock's nbdkit plugin, and sets SPINIFEX_REQUIRE_CONFORMANCE_TOOLS so a runner image that loses them fails instead of skipping. TestViperblockdConformance stands the provider handlers up over an embedded NATS and a real predastore and runs the same suite against them, which is what caught CopySnapshot accepting a foreign volume's snapshot on unencrypted volumes. * feat(viperblockd): honour read-only publish and advertise block size constraints ReadOnlyPublish was advertised false and read_only=true was rejected, so the capability was true only by omission. nbdkit -r now starts the export when the request asks for it, which sets the NBD read-only transmission flag and makes the plugin refuse writes. Access mode is fixed when nbdkit starts, so a republish asking for the other mode is refused with VolumeInUse rather than handed the running export. Block size constraints were absent entirely: the nbdkit Go binding has no block-size callback, so the plugin cannot advertise them. The blocksize-policy filter can, without a binding callback. Minimum 1 because viperblock's WriteAt handles unaligned requests with a read-modify-write, preferred 4096 to match its block size, maximum 32M to match what qemu-nbd advertises. * test(conformance): judge sparse reporting by the allocation map, not the context The subtest asserted that base:allocation was offered. nbdkit offers that context whether or not the plugin can compute extents, answering 'all allocated' when it cannot, so the assertion passed for a server with no extent support at all — it could not fail. What separates the two is the answer: a volume with nothing written to it is entirely holes to a server that really tracks allocation. Read the map with nbdinfo --map --json and compare holes against the advertised capability. qemunbdd reports holes and advertises true; viperblockd reports none and advertises false. * test(fixtures): keep SSL_CERT_FILE set for the fixture's whole lifetime The predastore fixture is one daemon per test binary, but its cert was exported with t.Setenv, which reverts when the first test that called Start finishes. In-process clients did not notice because crypto/x509 caches the pool behind a sync.Once, loaded while the variable was still set. Child processes did: nbdkit spawned by a later test inherited an environment with no SSL_CERT_FILE and could not verify the daemon, so the whole NBD client suite failed when the package ran as a whole while passing when run alone. Also install libnbd-bin in CI, so the NBD client suite runs there instead of failing on missing tools. * ci: install nbdkit-plugin-dev so the viperblock plugin can build * test(volume): give the snapshot fixture an owner CreateVolume now fails closed on a snapshot whose owner it cannot match, including an unset owner_id. The fixture predates that and wrote none, so the provider test failed with InvalidSnapshot.NotFound before ever reaching the provider. * test(integration): give the volume harness a real provider The control plane no longer builds volumes itself, so CreateVolume in the integration harness failed with "no EBS provider configured": the harness wired a VolumeServiceImpl with nothing behind it. It now serves viperblockd's provider subjects against the same predastore fixture, so the blocks are still written by real viperblock to a real daemon. Three persisted-state assertions moved with it. TenantID, VolumeType and AvailabilityZone are control-plane facts, held in the ebsmetadata document rather than viperblock's own state, so the storage oracle now asserts their absence and DescribeVolumes -- whose answer is account-scoped -- is what checks them. * refactor: route image import through the EBS provider and drop the legacy metadata path The control plane could still only run against viperblock: the AMI import and the ochre weights import both linked the storage library directly, and the ebsmetadata store kept a read fallback onto viperblock's config.json. Import now goes through the provider contract with no new verb: CreateVolume, PublishVolume, a bulk copy over the published NBD export with qemu-img, then UnpublishVolume and CreateSnapshot. Bulk data rides NBD rather than NATS, whose request size the contract caps far below a disk image. The migration scaffolding goes with it. ebsmetadata documents are now the only thing the control plane reads: no legacy prefix scan, no config.json fallback, no backfill on daemon start. config.json belongs to the provider, which is the single writer of it. ListAMIs keeps its tolerant/strict split. Skipping an undecodable document is right for DescribeImages, where one corrupt document must not hide the fleet, and wrong for a name-uniqueness check, which cannot rule out a name it failed to read. spinifex and cmd no longer import viperblock outside services/viperblockd and testutil/vbscan. * feat: add a volume enumeration verb so a lost document cannot strand blocks Making ebsmetadata documents the sole index of volumes left one failure with no recovery: a volume whose document is gone disappears from DescribeVolumes, from the leak reaper (which enumerates documents), and from the provider, whose contract had no verb that asks what it holds. ListVolumes closes that. It is capability-gated on VolumeEnumeration and paginated, following CSI's optional LIST_VOLUMES rather than inventing a shape. Refs are deliberately not Volumes: enumeration answers what exists, and a provider must not open every volume's engine to say so. Each implementation reads what actually exists rather than what it remembers. qemunbdd walks its volumes directory, not its in-memory map, which does not survive a restart; viperblockd walks the bucket's top-level prefixes. A volume the provider has forgotten is precisely what a caller is looking for. The consumer is a read-only orphan report: provider volumes minus documented ones, exposed as spx admin volumes orphans. It never deletes. An EFI store is excused only when its base volume is documented, so a stranded pair is still reported. Listing documents stays strict, because reporting a volume as orphaned on the strength of a document that failed to decode would point an operator at live data. * fix: stop the orphan scan accusing storage of holding things it does not A live env19 run reported three orphans against a healthy cluster: an AMI's backing volume, a snapshot, and the cluster key store. All three were wrong, and a report that cries wolf on a clean cluster is worse than no report. Enumeration treated every top-level bucket prefix as a volume. Snapshots sit beside volumes at that level and have a config of their own, so presence of a config cannot separate them; the snap- name is what does, which is already how the AMI removal path reads them back. keys/ and spinifex/ are not volumes at all. An AMI's blocks are a genuine provider volume, so enumeration keeps reporting them. What was missing is on the reading side: an AMI is recorded as an image document, not a volume one, so the scan now treats a documented image as known. Listing images is strict for the same reason listing volumes is — unreadable and absent are different answers, and only one means orphaned. * fix: let an orphaned image's blocks be reclaimed The orphan report tells an operator that reclaiming a stranded volume is their decision, and images remove --force is the tool it points them at. On env19 that tool failed on exactly those volumes: removal drops the ebsmetadata document first, and predastore answers NoSuchKey for a document that is already gone, which is the definition of an orphan. Deleting the document stays first and stays fatal. That ordering is the barrier that stops a launch landing on blocks about to be deleted, and an AMI still advertised after its blocks are gone is the worse failure. Only an already-absent document is now tolerated: the barrier is satisfied, and the blocks are the sole thing left to reclaim. S3ObjectStore.DeleteObject normalises a missing key the way GetObject already does, so this is recognised rather than matched on error text. The obvious unit test passed without the fix, because the in-memory store is silently tolerant on delete and real S3 answers 204 — neither behaves like the backend this runs against. The test now drives a store that reports the miss, and fails without the fix. * feat: add per-verb OTel spans to the EBS provider contract The ten provider verbs cross a single NATS seam and nothing measured it. The only spans on the storage path were the legacy ebs.mount/ebs.unmount pair, so control-plane storage latency could not be attributed to a verb or compared across provider implementations. NATSProvider.request is the one client-side funnel every verb passes through, including both legs of an owner-subject fallback, so a single span there covers the whole contract and measures what the control plane experiences regardless of which provider answers. Span names come from a closed verb set rather than the subject. Owner and snapshot-create subjects embed a volume ID and the mount/unmount subjects embed a node ID; naming spans after them would give every volume a span name of its own. The IDs move to attributes and an unrecognised subject collapses to a single unknown verb. Trace context rides the message headers, so the serving provider joins the caller's trace instead of rooting one of its own. The carrier is a copy of the one in spinifex/utils rather than an import: that package pulls in the aws-sdk and the cluster key store, which the wire contract must not depend on. Responses carry no shared accessor for their error field, so both sides re-read just that field from the encoded reply, and only when the span is recording. Without it a failed verb looks like a successful round trip. viperblockd serves the contract with its own handlers rather than natsserve, so its handlers now take the per-message context and its publish/unpublish pair drops the subject-named consumer span it opened for itself. * feat: add null and hostile providers, and a per-verb bench suite The provider boundary made it possible to put something other than viperblock behind the control plane, and nothing yet did. nullprovider is the floor. It is not a new type: MemoryProvider already answers every verb from a map and natsserve already serves any EBSProvider, so the package names that composition and states what it measures. On loopback with no storage behind it a round trip costs around 195us against 74ns in process, which is the seam's own price and is not attributable to any storage engine. conformance.RunBenchSuite prices one round trip per verb and drives every implementation through the same calls in the same order, so two providers' numbers are comparable. It measures control operations only: guest I/O never crosses these verbs. hostile wraps any provider in one that misbehaves. Faults derive from the seed and a per-target sequence rather than a global counter, so concurrent callers on different volumes cannot reorder each other's faults and a failure found deep into a soak run replays exactly. Error and error-after-work are separate faults on purpose: the second reports failure after the work has already happened, which is how an orphan is made, and is what makes an enumeration scan the right oracle for a soak. Enumeration itself is never faulted, since an oracle that can be told what to say cannot falsify anything. The soak asserts that every volume the provider still holds is attributable to an injected fault. A leftover with nothing behind it is the control plane losing track of storage on its own. Two bugs were found by falsifying the new tests rather than by running them. The FNV-derived draw clustered badly enough that two fault bands were never reachable in 1200 draws, so the draw now goes through a SplitMix64 finalizer. And the first version of the lie test was worthless: MemoryProvider returns copies, so a lie could not corrupt it whether or not the injector copied, and the test now drives a provider that hands out pointers into its own state. * test: bench the provider contract against qemunbdd and a live viperblockd RunBenchSuite was only ever pointed at the null provider, so the numbers priced the seam and nothing else. Point it at the two real implementations. BenchConfig gains a VolumeBytes knob: 1 GiB per iteration is fine against a provider that stores nothing and wrong against one that does, so qemunbdd and viperblockd are both measured at 64 MiB. liveProvider splits into a testing.TB flavour. Benchmarks need the same connection and the same node and cannot be handed a *testing.T. * fix(viperblockd): carry the trace context into every viperblock engine call Both S3 clients only emit a span when the request already carries one, so calling the no-context Init, LoadState, SaveState, LoadBlockState and Close left the whole engine open untraceable. Every provider verb traced as one flat server span, and the 342ms describe measured on env19 could not be attributed to anything. viperblock already exposes the Ctx variants and Backend already declares InitCtx, so this is threading, not new instrumentation. openVolumeVB, openLoadedVolumeVB, sealVolumeVB, describeVolumeEngine, snapshotVolumeEngine, copySnapshotOnVolume, seedVolume and applyConfigUpdate now take a context, and mount/unmount keep the context their own span derives instead of dropping it. completeCreateSnapshot gets WithoutCancel: the background half of accept-then-publish has to outlive the request it was accepted by and still be attributable to it. The per-volume ebs.config handler opens a consumer span like the other legacy subjects, so a config update is no longer the one path with no trace at all. * perf: describe a volume without opening an engine on it describeVolumeEngine fell through to openVolumeVB for any volume not mounted on the node serving the request, which constructed a full viperblock engine to read one integer. On env19 that decomposed as a 22 ms reachability list, a 3 ms state read and a 16 ms PutObject of the volume's own config.json — the write coming from the SeqNum bootstrap a read-write open performs. Use viperblock's read-only state load instead. A describe is now the 3 ms read: no background goroutines, no reachability probe, no SeqNum window claimed, and no write issued by a worker that does not own the volume. Falsified: restoring the openVolumeVB call fails TestDescribeVolume_ReadsWithoutOpeningTheVolume on both the write and the list, with the fake backend answering each so neither assertion hides behind the other. * perf: share one HTTP client across every viperblock backend Four sites built the same S3Config by hand, each leaving HTTPClient unset, so every engine open and state read got its own connection pool and paid its own TLS handshake. That was invisible while Backend.Init issued a whole-bucket list — the list paid for the connection and the state read rode it — and it became the dominant cost once describe was reduced to a single request. Route all four through cfg.volumeS3Config, which builds the client once. Falsified: dropping the HTTPClient field takes TestDescribeVolume_ReusesOneConnection from one connection to three. * perf: wait for nbdkit to be ready instead of waiting a fixed second mountVolume spawned nbdkit and then ran a confirm loop until a one-second deadline passed. The loop only broke early when the process exited, so the fast-failure path worked and the success path always cost the full second. That second was ~1015 ms of a ~1040 ms publish, and it emitted no spans, so the timings never contradicted the assumption that it was process spawn. Wait for the endpoint to accept a connection instead. That is also the question the caller needs answered, since it is about to hand the URI to something that will connect to it — where 'still alive after a second' only correlates with it. A nbdkit that exits during startup still fails the mount immediately, and one that never comes up now fails on a deadline rather than being assumed healthy. Falsified: reintroducing a fixed sleep in pollUntil fails both the readiness timing assertion and the fast-failure one. * test: measure the data path, not just the control verbs The conformance benchmarks price create, publish and describe. Guest I/O never crosses those verbs, so none of those numbers say anything about what a guest experiences. This drives the published export with qemu-img bench, which sits on the same block layer virtio-blk does. It asserts only that the I/O completes and logs a table: what a given store is capable of is not a contract, and pinning a number here would only produce a flaky test. Read profiles stay inside the region the write profiles covered, or they would be timing how fast the export answers with zeroes, and one write profile flushes, because an unflushed write measures how fast the WAL accepts data rather than how fast the store takes it. Profiles are spaced apart because the plugin tears an engine down per disconnect and removes the volume's local directory as it goes, so a connection opened while the previous one is closing fails its handshake. * test: run data-path profiles back to back The spacing was a workaround for a volume lock that did not hold across close. With that fixed, consecutive profiles are worth more than the workaround was: each is its own NBD connection, so a run that completes has also shown that an arriving connection waits out the previous one's close rather than racing it. * fix: refuse a delete that cannot establish whether a volume is published volumeMountedElsewhere returned false on every failure path, including a request timeout, so a busy or partitioned owner was indistinguishable from no owner at all and the delete proceeded. Deleting a published volume leaves the nbdkit export and the guest writing through it alive over storage that is going away. Report the three outcomes separately. NATS distinguishes no-responders from no-answer, so only the former means unmounted; an unanswered probe is refused and the caller may retry once the owner is reachable. * feat: exclude a second viperblock engine with a JetStream volume lease Nothing in the stack stopped two viperblock engines opening one volume from different nodes. For an encrypted volume that is not just a consistency risk: the AES-GCM nonce is fully consumed by SeqNum, VolumeUUID and a domain byte, and the SeqNum window claim is a read-then-write with no CAS, so two engines opening concurrently issue overlapping nonces under the same key. Every engine open now takes a lease first, keyed by volume in a JetStream KV bucket. A lease is a KV create, which JetStream serialises, so a second claimant loses instead of both winning. The revision that won is the generation: monotonic across the bucket, so a later opener always carries a higher one than the writer it displaced. Entries carry a TTL and a renewal loop, so a node that dies mid-mount does not wedge its volumes forever. Losing a lease is logged, not enforced. Until the object store can refuse a stale writer's PUT, failing live guest I/O on lease loss would add a failure mode without stopping the zombie it is aimed at. A daemon with no lease store refuses to open rather than opening blind, so nbdkit recovery binds the store before it adopts surviving exports. Repeat acquisitions on one node share a lease: the unmount seal opens a detached engine while the mount being torn down still holds it, and cross-node exclusion is what the lease is for. A restart reclaims this node's own stale entries, since the exports that outlived the daemon are still running. * refactor: consume masterkey from bluebottle in the test this branch added * feat(ebsprovider): classify refusals a caller may retry Every ErrorCode said what went wrong and none said whether the same request could succeed later, so a caller could not tell a permanent refusal from a transient one. Transient conditions shipped as internal, which tells a caller to give up when it should retry. Adds ErrUnavailable / ErrorCodeUnavailable and ErrorCode.Retryable(), which callers branch on instead of on the code itself. DeleteVolume's "could not establish whether the volume is published" refusal moves off internal onto it: the owner that did not answer may answer later. TestErrorCodeRetryable names every code, so adding one without deciding its retry meaning fails rather than silently defaulting to permanent. TestClassifyError pins the sentinel-to-wire-code mapping, which had no coverage at all; a sentinel missing from classifyError falls through to internal and loses both the reason and the retry signal. * fix(ebsprovider): drop CopyOnWriteClone, which no request can ask for Four providers advertised the capability and nothing consumed it: there is no clone verb on the interface. CreateVolume's SourceSnapshotID restores from a snapshot and CopySnapshot duplicates snapshot metadata; neither is a volume clone, and the field documenting SourceSnapshotID says so explicitly. CSI expresses clone as a volume_content_source with a volume source, which this contract does not implement. Advertising it told a caller a feature was available and then gave them no way to use it. Removed rather than backed by a method: adding a clone verb is a feature, not a contract fix, and the capability can come back alongside it. The Capabilities doc comment now states the rule, and qemunbdd's stale comment about sparse extents is corrected while there. * feat(ebsprovider): add ListSnapshots so snapshots are reconcilable The contract could create, copy and delete snapshots but never say which ones it held. That left the control-plane metadata document as the only index of them, so losing one stranded the data it pointed at with no way to find it again. This is the same exposure ListVolumes closed for volumes, and it stayed invisible because ListSnapshots is optional in CSI too. ListSnapshots pages exactly as ListVolumes does, gated on a new SnapshotEnumeration capability. SnapshotRef is deliberately not a Snapshot: enumeration answers what exists, and reading a snapshot's size or state can cost far more than listing it. viperblockd walks the bucket's snap- prefixes, sharing the top-level walk with ListVolumes. It leaves SourceVolumeID empty because the link lives inside the snapshot's own encrypted state and reading it would mean a fetch per snapshot listed. qemunbdd walks its snapshots directory rather than its in-memory map, so a snapshot that outlived the process still appears; its SourceVolumeID is empty in that case for the same reason CreateSnapshot refuses to reuse the ID. Five conformance subtests cover it, and they run green against MemoryProvider, qemunbdd and viperblockd over a real predastore. * feat(ebsprovider): state the exclusion guarantee in the contract A caller could not tell which providers prevent two writers from holding one volume, at what scope, or for how long. The guarantee existed in viperblockd and was invisible from the outside, which is why the conformance suite had no concurrency dimension at all. Capabilities.Exclusion states it, and deliberately separates three questions the contract used to run together: how far exclusion reaches (none, node, cluster), whether a dead owner's claim ever expires, and whether a writer that lost its claim is actually stopped. That last one matters most and is the least flattering: exclusion refuses the second opener, fencing stops the first. viperblockd advertises cluster scope with a 45s TTL and FencesLostClaim false, because a partitioned node whose lease lapsed keeps writing until the object store can refuse it. Four new conformance subtests. Two required a second viperblockd node in the harness: cluster exclusion cannot be exercised by one node, because the second publish goes to a subject nobody serves and times out rather than being refused. Both nodes share the NATS the leases live in and the bucket the volumes live in, so a refusal comes from the lease. Standing that second node up immediately found a real gap, in a test that had been silently skipping for want of one. A publish refused by another node's lease came back as internal rather than volume_in_use, so a caller was told something had broken when the answer was that someone else held the volume. Mapped in handlePublishVolume. * build: pin viperblock to the release carrying the provider's dependencies The branch has been building against a local replace pointing at a viperblock worktree, so its committed pin never actually built: it named a version without CopySnapshotMeta, ErrSnapshotVolumeMismatch, NewStateReader or s3.NewHTTPClient, all of which this branch calls. Points at the merged viperblock dev instead and drops the replace. GOWORK=off now builds clean, which is the deploy path ansible uses. * fix: let viperblockd's delete sweep tolerate an object another sweep removed deleteObjectPrefix claimed to mirror handlers/ec2/volume's deleteS3Prefix and give DeleteVolume and DeleteSnapshot idempotent-when-absent behaviour, but it returned on any DeleteObject error. Two overlapping deletes for one volume left the loser reporting an internal failure once the winner had removed a chunk between the list and the delete. The control-plane copy that carried this fix is gone with the embedded engine path, so the provider path reintroduced the bug it had just fixed. * fix: stop CreateVolume leaving local state on whichever node served it A state read prefers this node's local copy over the backend, and provider RPCs are not owner-routed, so the node that happened to serve a create kept a copy that answered describe as if the volume still existed after another node deleted it. The two-node conformance harness caught it as DeleteVolume/success failing about one run in three. The seeded path already removed its local files after closing. The unseeded path saved state and left them, which was the only difference between the two. * fix: guard the mount path itself against a second export of one volume handlePublishVolume refused a volume this node already exported, but mountVolume did not, and the legacy ebs.<node>.mount subject is the route production takes for instance launch and hot-attach. A retried attach racing a fresh one started two real nbdkit against one volume, with no refusal and no warning: the volume lease only refuses a different node, and a same-node re-acquire finds the volume already held and increments its refcount. That also made the advertised exclusion inaccurate. viperblockd claims cluster-scoped exclusion on the grounds that a second opener is refused, while the conformance subtests reach it only through PublishVolume, so they passed with the legacy route unguarded. Moving the check into mountVolume gives both entry points the same behaviour and makes the claim true for the path production uses. * fix: tolerate a missing legacy AMI config on deregister DeregisterImage deletes the AMI document, then the pre-provider {imageID}/config.json. Predastore answers a delete of an absent key with NoSuchKey, and that was treated as fatal, so every AMI created since the metadata store landed failed to deregister after its document was already gone. A retrying caller then saw InvalidAMIID.NotFound for an image it had just been told it could not delete. The regression test uses a store that answers a missing-key delete the way Predastore does; MemoryObjectStore silently succeeds, which is why the unit suite stayed green. * fix: reap ENIs left behind by an abandoned instance launch A launch creates the instance's ENI and then attaches it. When the daemon dies in between, the record survives with no instance and nothing ever looks at it again. The security group dependency check counts an ENI that lists the group, so the group cannot be deleted for as long as the record exists. The in-process launch path already rolls back on error; a process that dies cannot. This adds a cluster-wide sweep over records that are launch-created, never attached, and older than the launch RPC timeout by a wide margin. The description prefix is now a shared constant because it is the only thing separating an abandoned launch from a standalone ENI a caller asked for.	2026-08-12 16:54:19 +10:00