…

Why

aicr models cluster state as a Snapshot of Measurements (K8s, GPU, OS, SystemD, NodeTopology). NodeTopology is cluster-wide and only carries node taints + labels. The model has no slot for per-hardware-group network topology -- PFs and their PCI addresses, rails, NUMA, RDMA capability, link type, kernel module lists, machine/GPU identity -- which makes it impossible to recipe or validate networking beyond a single all-or-nothing network-operator toggle.

k8s-launch-kit (l8k) already discovers exactly this data via its cluster-config.yaml. The intended integration is library-mode: l8k imports pkg/measurement and emits *Measurement values directly that aicr Snapshots can consume. The dependency direction is l8k -> aicr; the Measurement schema is aicr's contract.

This commit is Phase 1 -- the schema affordances l8k needs to implement that contract. No l8k import is introduced here; the snapshotter and CLI are untouched. The producer side (Phase 2, in the l8k repo) and the consumer side (Phase 3, the aicr collector + CLI flag) land separately.

Part of #828

What changes

Schema additions to pkg/measurement:

• New TypeNetworkTopology enum value. Today at most one Measurement of this Type per snapshot, keeping all find-first-by-Type consumers (constraints extractor, recipe validation, diff indexing, fingerprint) correct. Multi-instance support is a deliberate future step.

• New Subtype.Items []ItemEntry field. ItemEntry mirrors Subtype's scalar contract: Data map[string]Reading for scalar measurements plus Context map[string]string for descriptive metadata. This lets homogeneous record lists (per-PF entries under a pfs subtype) be represented as real YAML arrays rather than packed-string-encoded scalars or numbered subtypes (pf-0, pf-1, ...). Reading itself is NOT extended -- it stays scalar-only.

• Custom UnmarshalJSON/UnmarshalYAML on ItemEntry so Reading values inside ItemEntry.Data round-trip the same way they do in Subtype.Data today.

• Subtype.Validate relaxed: a subtype is valid with either non-empty Data or non-empty Items (or both). The existing len(Data) > 0 invariant predated Items.

• Items carries omitempty so subtypes that don't use it serialize byte-identically to today's output. Data's tag also gains omitempty so Items-only subtypes don't emit a noisy data: {}; this is behavior-safe because every existing subtype satisfies len(Data) > 0 (Validate guaranteed it).

• New SubtypeBuilder helpers: WithContext(k, v), WithContextMap(map), WithItem(entry), WithItems(slice).

Constraint path grammar extension in pkg/constraints:

• New optional item-selector segment: {Type}.{Subtype}[<selector>].{Key}. Two selector forms:
  Index: NetworkTopology.pfs[0].rail
  Predicate: NetworkTopology.pfs[rail=3].pciAddress
  Predicates evaluate against ItemEntry.Data first, then
  ItemEntry.Context. First match wins; multiple matches return
  ErrCodeConflict. Key resolution inside the matched entry tries
  Data then Context. Paths without a selector continue to use the
  legacy Subtype.Data lookup unchanged.

OpenAPI (api/aicr/v1/server.yaml):

• Measurement.type enum corrected from the stale [systemd, os, k8s, gpu] to match measurement.Types: [K8s, GPU, OS, SystemD, NodeTopology, NetworkTopology]. The pre-existing miss (NodeTopology and SystemD were never added) is bundled into this fix.
• New ItemEntry schema mirroring data + context.
• Subtype gains an optional items array property; data is no longer required at the schema level (Validate still enforces "at least one of data/items").

Docs:

• New docs/integrator/measurement-api.md publishing the cross-repo Measurement schema contract: Type cardinality table, Subtype layout rules, the NetworkTopology shape (subtype names, what lives in Context vs Data, item structure for pfs), and the constraint-path grammar including selectors. l8k's Phase 2 implementation targets this spec.
• pkg/measurement/doc.go updated to flag the package as part of aicr's cross-repo public API surface.
• docs/integrator/index.md adds the new page to the integrator TOC.

Testing

• pkg/measurement/types_test.go: Items-only subtype validation, JSON + YAML round-trip of Items with Reading values inside ItemEntry, byte-identity check that pre-existing Items-less subtypes don't suddenly emit an items: key.
• pkg/measurement/builder_test.go: 100% coverage on each new builder helper (WithContext / WithContextMap / WithItem / WithItems).
• pkg/constraints/extractor_test.go: parser tests for both selector forms and every error path; ExtractValue tests for index/predicate hits, out-of-bounds, no-match, no-items, ambiguous-predicate (ErrCodeConflict).

Coverage on touched packages vs main:

pkg/measurement: 96.0% -> 96.6% (+0.6%)
pkg/constraints: 80.9% -> 87.6% (+6.7%)

go test ./... passes (the pre-existing pkg/trust sandbox failure is unrelated -- it writes to ~/.sigstore which is outside this environment's write allowlist; passes outside the sandbox). go vet ./... clean. golangci-lint not available in this environment per project notes -- run make qualify before pushing.

Not in this commit

Phase 2 (in the l8k repo): embed l8k's discovery-only runtime artifacts (presets, default config; profiles deferred), rename LaunchKubernetesConfig -> LaunchKitConfig, add a library-friendly Discover(ctx, kubeClient) entry point, vendor aicr's pkg/measurement, and add DiscoverMeasurements / ParseClusterConfigMeasurements wrappers that emit *aicrmeasurement.Measurement values per the contract this commit publishes.

Phase 3 (in aicr): new pkg/collector/network/ calling l8k's library, --cluster-config / --discover-network flags on aicr snapshot, RBAC additions for the agent Job, single-group enforcement.

Multi-group NetworkTopology is a future iteration; the consumer rewrites it requires (constraint @ grammar, recipe-validator iteration, diff (Type, identifier) keying, fingerprint group-aware logic) are deliberately deferred until the single-group integration has shaken out.

Summary

Motivation / Context

Fixes:
Related:

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Build/CI/tooling

Component(s) Affected

• CLI (cmd/aicr, pkg/cli)
• API server (cmd/aicrd, pkg/server)
• Recipe engine / data (pkg/recipe)
• Bundlers (pkg/bundler, pkg/component/*)
• Collectors / snapshotter (pkg/collector, pkg/snapshotter)
• Validator (pkg/validator)
• Core libraries (pkg/errors, pkg/k8s)
• Docs/examples (docs/, examples/)
• Other: ____________

Implementation Notes

Testing

# Commands run (prefer `make qualify` for non-trivial changes)
make qualify

Risk Assessment

• Low — Isolated change, well-tested, easy to revert
• Medium — Touches multiple components or has broader impact
• High — Breaking change, affects critical paths, or complex rollout

Rollout notes:

Checklist

• Tests pass locally (make test with -race)
• Linter passes (make lint)
• I did not skip/disable tests to make CI green
• I added/updated tests for new functionality
• I updated docs if user-facing behavior changed
• Changes follow existing patterns in the codebase
• Commits are cryptographically signed (git commit -S) — GPG signing info