ateom: add GetWorkloadStats RPC and retain actor attribution

[Tim Bai (baizhenyu)]

Phase 0 of #550, tracked by #594. First of three stacked PRs.

Adds ateom.Ateom/GetWorkloadStats, the RPC atelet will poll for per-actor resource
usage, plus the actor attribution both ateom runtimes need to label a sample. The measurement half of each runtime lands in the two follow-ups;
GetWorkloadStats returns Unimplemented until then, so this change puts nothing
half-populated on the wire.

The RPC

GetWorkloadStats is a pure read: unlike RunWorkload / CheckpointWorkload /
RestoreWorkload it does not move the ateom between "available" and "executing",
so it is safe to call on a timer for a workload's whole lifetime.

The request carries the actor UID the caller believes is executing here. A worker
can be recycled between atelet's view of the world and the call landing, so a
mismatch is rejected with FAILED_PRECONDITION rather than reporting a different
actor's numbers under the requested actor's identity. FAILED_PRECONDITION is
also the answer when the ateom is available — there is nothing to measure.

The response is one sample, measured at sandbox granularity (which today
equals the actor; per-container attribution would need the gVisor sentry's own
accounting). It echoes the measured actor's identity so the caller can attribute
the sample without holding its own worker→actor mapping, and carries
sandbox_class and source so two differently-measured numbers are not silently
compared as though they were the same thing. Both are enums — closed sets the
ateom binary picks from, where a typo in a free-form string would silently split
a metric in two downstream.

Attribution retention

Neither runtime kept the actor's identifying fields past the call that started the
workload — they arrive on Run/Restore and nothing downstream needed them. A usage
sample is only useful once attributed, so both now hold them for as long as they
are executing:

• ateom-gvisor gains AteomService.activeActor, set by RunWorkload and
  RestoreWorkload, cleared by CheckpointWorkload and by both boot-failure
  paths — tracking exactly the available/executing state machine on the service.
• ateom-microvm gains runningActor.activeActor, populated from the existing
  actorBootParams on both the cold-boot and restore paths; the existing delete
  from s.running in teardownActor clears it.

The extraction from the request is shared in internal/ateomstats, since both
binaries need the same mapping. ActorAttribution composes the existing
resources.ActorRef rather than repeating its two fields, so the actor's
Atespace stays visibly attached to the actor — worth noting because
TemplateNamespace beside it is an unrelated namespace (a Kubernetes one;
ActorTemplate is a namespaced CRD, while an atespace is Substrate's own
tenancy unit).

It is deliberately not called ActorIdentity: "actor identity" already means
a credential in this repo — the ateapi.ActorIdentity service, substratex509,
ateompath.ActorIdentityDirPath, and #670 building on all three. Nothing in this
type is a secret or is presented as proof of anything; it is the tuple a usage
sample is labeled with.

Reviewer notes

• activeActor has no reader in this PR. It is written and cleared but never
  read, because both GetWorkloadStats bodies are still stubs. The readers arrive
  with the measurement in the two follow-ups; the stub comments point there.
• No metric labels are added here. The response carries actor and atespace
  identity, but that is a sample, not a datapoint. Per the decisions in Observability At-Scale #174,
  actor/atespace identity belongs in logs and traces rather than as TSDB labels,
  and only template-level dimensions become metric labels. That conversion is
  atelet's, in Phase 1/2.
• cpu_usage_usec resets on restore. A restore recreates the sandbox, so the
  counter restarts at zero while the actor UID stays the same. Documented on the
  field; callers computing deltas must treat a decrease as a reset. If that proves
  too subtle in practice, an explicit epoch marker is a backward-compatible
  addition later.
• workerpool_name is deliberately absent. atelet does not know it today;
  adding the field later is backward compatible.

Testing

• internal/ateomstats — TestActorAttributionFromRequest pins the mapping from
  both request types, including the empty and nil cases (the callers are not
  defensive about the request pointer, so the nil-safety of the generated getters
  is load-bearing). Five deliberately distinct placeholder values, so a field
  wired to the wrong source is visible.
• cmd/ateom-microvm — TestActorBootParamsAttribution pins the
  actorBootParams → ActorAttribution mapping, and
  TestActorBootParamsAttributionMatchesRequest checks that the two hops (request
  → boot params → attribution, written in different files) compose back into what
  the caller sent.
• Both runtimes — TestGetWorkloadStatsUnimplemented pins the stub's advertised
  contract, and TestAteomServiceStartsAvailable checks a fresh gVisor service
  retains no attribution (a non-nil zero value there would make an idle ateom
  report an empty actor's usage instead of refusing).
• Not unit-tested: the gVisor set/clear transitions. RunWorkload,
  RestoreWorkload and CheckpointWorkload each reach for netlink, runsc and the
  worker pod's netns within a few lines of entry, so there is no seam to drive
  them from go test. Noted in cmd/ateom-gvisor/stats_test.go rather than
  covered with a fake; the transitions get verified end to end once
  GetWorkloadStats returns real data.

Both ateom packages are //go:build linux, so their tests do not execute on
darwin. They were run natively on a Linux host in addition to the local
compile-check, along with hack/verify/shellcheck.sh (which needs docker).

Still ahead

• PR 2 — gVisor: read the sandbox cgroup. Reads /sys/fs/cgroup/pause, not
  main/: every application process runs inside the sentry, which is a single
  process in pause/.
• PR 3 — micro-VM: read the guest agent's StatsContainer over the existing
  vsock connection, not the host cgroup (guest RAM is a fixed allocation, so the
  host cgroup barely moves with the workload). Closes Phase 0: StatsWorkload RPC on ateom (proto, both runtime reads, identity retention) #594.

[Da Huang (git286)]

I would recommend to name it GetWorkloadStats (and rename the request and response as well) to follow the AIP standard: https://google.aip.dev/131

[Tim Bai (baizhenyu)]

Done — GetWorkloadStats, GetWorkloadStatsRequest, GetWorkloadStatsResponse. Agreed that StatsWorkload read as if "Stats" were a verb.

One note on how far I took AIP-131: §3.1 of docs/api-style-guide.md also says the response must be the resource itself rather than a ...Response wrapper, which would make this returns (WorkloadStats). I kept the Request/Response pair as you wrote it, since the rest of this internal service (RunWorkload, CheckpointWorkload, RestoreWorkload) is paired that way and a sample is not really a addressable resource. Happy to go the other way if you prefer the strict reading.

[Da Huang (git286)]

Should we make it an enum?

[Tim Bai (baizhenyu)]

Done — SandboxClass enum with SANDBOX_CLASS_UNSPECIFIED / _GVISOR / _MICROVM, following §5.1 of the style guide (prefixed values, _UNSPECIFIED zero) and matching the existing SnapshotScope in this file. The values mirror the ate.dev/v1alpha1 SandboxClass the WorkerPool and ActorTemplate are configured with.

[Da Huang (git286)]

Same, should we make the source an enum?

[Tim Bai (baizhenyu)]

Done, same treatment — StatsSource with STATS_SOURCE_UNSPECIFIED / _CGROUP / _GUEST_AGENT. _UNSPECIFIED carries the "no measurement was taken" meaning the empty string used to, so the "all four measurements are zero" case is still distinguishable from a real zero.

[Da Huang (git286)]

Is it too late to set nil here? What if listSnapshotFiles failed above?

[Tim Bai (baizhenyu)]

Good catch — that was a real bug, fixed.

listSnapshotFiles can return early, and by that point cmdCheckpoint / cmdFsCheckpoint has already destroyed the sandbox, so the ateom would have kept advertising a checkpointed actor as live for whatever GetWorkloadStats calls arrived before atelet recycled the worker.

Moved the clear to immediately after the snapshot switch, which is the exact moment the sandbox stops existing. Everything below it (cleanupContainersAfterCheckpoint, UnmountAllUnder, CleanupActorNetwork, listSnapshotFiles) is bookkeeping over a dead sandbox. Deliberately nothing above it clears: a checkpoint that failed may well have left the workload running, and reporting its usage is the honest answer there.

I checked the micro-VM CheckpointWorkload for the same shape and it does not have it — the guest is only Paused until teardownActor, so every early return leaves a live VM still in s.running, and teardownActor / delete(s.running, ...) are adjacent with nothing fallible in between.