[chou-godaddy]

Related issue

Fixes #23

Summary

NVIDIA/OpenShell#5048, merged after v0.1.7, moves supervisor sandbox identity from the top-level container object to device.container. ans-ocsf-hydrator reads only the top-level field, so every record from an upgraded supervisor is unmapped: a fully upgraded fleet fails the run, and in a mixed fleet the upgraded sandboxes silently get no new observation. This PR reads device.container first and falls back to the top-level container.

Changes

• Sandbox resolver (internal/hydrator/event.go): Event.Sandbox() returns device.container when it has a UID or name, otherwise the top-level container. The device's own uid, name and hostname are not decoded: upstream leaves uid and name empty on supervisor records and sets them to the gateway installation name on gateway records.
• Call sites (agentmap.go, aggregate.go, activity.go): agent lookup, the NoContainer count and the activity sandbox key (decision times, destination keys, policy context) use the resolver. No other logic changes.
• Docs: doc.go, the NoContainer comment in run.go and deploy/examples/hydrator.yaml name both locations and drop the removed schema-downgrade wording. Report.NoContainer and the no_container log key keep their names; they now mean no sandbox in either location.

A record whose device.container matches no agent is not matched again through a top-level container. Upstream emits one shape per record, and its OCSF validator rejects a top-level container.

Testing

• go test -race ./..., go vet ./..., gofmt and golangci-lint v2.10.1: all pass, 0 issues. Library coverage 98.5%.
• Unit tests cover resolver precedence (top-level only, device only, both, a device without a container, an empty device.container, a device identity without a container), lookup by device.container UID and name, and policy context keyed by device.container, including a policy record before the window.
• Rewriting existing fixtures to the new shape, for every sandbox and for a mixed fleet, gives byte-identical reports, legacy batch bodies and activity evidence.
• Validated against a real OpenShell supervisor from upstream's dev build of main at 1cdfe70 (0.1.8-dev.29+g1cdfe7088), nine commits after fix(ocsf): validate sandbox attribution against exported schemas NVIDIA/OpenShell#5048. Its records carry the sandbox only in device.container. The hydrator on current main attributed 0 of 14 captured records; with this change it attributes 14 of 14. The 14 records are included unedited as internal/hydrator/testdata/supervisor-device-container.jsonl, and TestRunUpstreamDeviceContainerCapture runs them with the agent mapped by sandbox UID and by name. The capture comes from a pre-release, so it should be refreshed if the shape changes before OpenShell's next release.
• With Sandbox() reduced to return e.Container, the device.container tests fail.

Out of scope

Gateway-origin records, which carry the sandbox in resources or unmapped.sandbox_id: the hydrator's input is supervisor records only (README). Removing the top-level fallback, once OpenShell releases before the change are no longer supported.

AI assistance

Assisted-by: Cursor (Claude Opus 5.5)

Checklist

• The PR title follows Conventional Commits — release notes are generated from it
• Tests cover the change
• I linked the relevant issue or proposal, or explained why no separate issue is needed
• Every commit is signed off (git commit -s) certifying the DCO

[kperry-godaddy]

Approving. This is the hydrator's half of NVIDIA/OpenShell#5048: upstream moved supervisor sandbox identity under device.container after v0.1.7, and without this change every record from an upgraded supervisor lands in Unmapped, which fails a fully upgraded fleet outright and silently drops the upgraded sandboxes in a mixed one. Routing all three readers through one Event.Sandbox() accessor is the right shape for it: the precedence rule lives in one place, the top-level fallback is contained in one function to retire later, and decoding only the device's container keeps a gateway record's device.uid and device.name (the installation name) from ever being mistaken for a sandbox. I checked that claim against upstream's Device::gateway and Device::linux constructors on main; it holds.

What I verified at a9dfd5d: build, vet, gofmt, go test -race ./... and golangci-lint v2.10.1 under Go 1.26.9 are clean; hydrator coverage is 98.0% with Sandbox, Lookup, attributor.add and activitySandbox fully covered. Three mutations of the resolver (device-only, fallback removed, empty device.container guard removed) each fail at least one test, so the new behaviour and the legacy path are both pinned. The 14-record capture carries no credentials; the only environment detail in it is the dev address noted inline.

Two notes inline, neither blocking. One item for later rather than for this PR: once v0.1.8 ships, refreshing testdata/supervisor-device-container.jsonl from the release build would retire the pre-release caveat in the PR body.