feat(api): Add blkio cgroup tuning via --blkio flag

[chrisgeo]

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Motivation and Context

Closes #1512.

Adds block I/O cgroup tuning to container run / container create so
compose translators (e.g. container-compose) can pass through Docker
Compose service.blkio_config instead of warn-skipping it.

The CLI shape follows the grouped, repeatable key=value form proposed in
#1512 (comment):

container run --blkio weight=500 ...
container run --blkio device=/dev/sda,weight=700,leaf-weight=300 ...
container run --blkio device=/dev/sda,read-bps=1048576,write-bps=1048576 ...
container run --blkio device=/dev/sda,read-iops=1000,write-iops=1000 ...

The device= value accepts either an absolute host path (resolved via
stat(2) for major/minor) or a literal <major>:<minor>. Keys allowed
on a per-device spec: weight, leaf-weight, read-bps, write-bps,
read-iops, write-iops. Keys allowed on a global spec (no device=):
weight, leaf-weight. Parser rejects unknown keys, conflicting
global weights, and global-only keys mixed onto device-less specs.

Runtime plumbing

Block I/O propagates as ContainerConfiguration.Resources.blockIO
(serialised as ContainerizationOCI.LinuxBlockIO) and is converted to
Containerization.LinuxBlockIO at the runtime boundary in
RuntimeService.configureContainer.

Dependency

Depends on apple/containerization#739, which introduces
Containerization.LinuxBlockIO (the Sendable wrapper around the OCI
type) and wires it into LinuxContainer.Configuration. While that PR is
unmerged this branch pins containerization to the PR branch
(full-chaos/containerization@feat/chaos-1380-blkio-runtime,
revision 3d009df). Before merge, the pin must be moved back to
apple/containerization at whatever revision lands #739.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

swift build clean, swift test --filter ParserTest passes
(105 tests, 5 new):

• testResourcesBlockIOFlags — combined global + per-device + throttle
• testResourcesBlockIOAcceptsMajorMinorLiteral — device=8:0 literal
• testResourcesRejectsInvalidBlockIOWeight — weight outside 10..1000
• testResourcesRejectsUnknownBlockIOKey — typo detection
• testResourcesRejectsGlobalKeyOnDeviceSpec — read-bps without device=

container run --help confirmed renders the new --blkio flag.

[chrisgeo]

Pushed 5d11a29 addressing review feedback.

1. blockIO no longer lives on ContainerConfiguration

Per the suggestion on ContainerConfiguration.swift, the field is now on LinuxRuntimeData and is carried opaquely through RuntimeConfiguration.runtimeData:

• CLI (ContainerRun / ContainerCreate) calls Parser.blockIO(specs:), wraps the result in LinuxRuntimeData(blockIO:), JSON-encodes it, and passes it as runtimeData to ContainerClient.create.
• RuntimeService.bootstrap reads RuntimeConfiguration.runtimeData from disk and threads it into configureContainer, which decodes LinuxRuntimeData and applies czConfig.blockIO.
• ContainerConfiguration.Resources.blockIO is removed; Parser.resources no longer takes blkio.

This keeps OS-specific options out of the generic container config type, as you described.

2. --blkio reshaped as options under Flags.Management

• The flag moved from Flags.Resource to Flags.Management (it shows up under MANAGEMENT OPTIONS in container run --help now).
• Help text collapsed to a single line: Block I/O cgroup tuning options (Linux only; see command reference for the supported keys). The detailed key/value schema will live in the command reference doc rather than the help wall.
• The structured key=value parsing in Parser.blockIO is unchanged, so existing behavior is preserved.

3. Tests

swift test --filter ParserTest — 105 tests pass, including the 5 blkio cases (now rewired to call Parser.blockIO directly since the field is gone from Resources). RuntimeConfigurationTests also still pass.

Deferred cleanup

The three self-review notes on Package.swift, Package.resolved, and .gitignore are intentionally left for now:

• Package.swift / Package.resolved still pin to the containerization#739 branch because that upstream PR is still open. They will revert to apple/containerization at whatever revision lands [container-run-create]: add support for --network none #739, as the PR description notes.
• .gitignore shows no diff against main on the current branch, so there is nothing to revert there — flagging in case I'm missing something on your end.