fix(sdk): preserve error context and cover tunnel policy updates

[WenYuLuo]

Preserve structured backend failures at the public AKernel boundary and keep reverse tunnels usable across network-policy updates. Package the matching ADX 0.1.0rc2 platform/Execd release, Environment SDK and source revision.

• Expose optional service codes, retry/outcome guidance, request identities, HTTP status and scheduling diagnostics on BackendOperationError, retaining the original cause. Cover confirmed cancellation, ambiguous create outcomes and unstructured errors.
• Exercise creation-time block, live block/clear/reblock and consecutive policy updates through the same public Sandbox/tunnel handle with default and custom ports. Require recovery within 10 seconds and retain command, file, PTY, published HTTP, outbound-denial and cleanup checks.
• Pin both release archives by SHA-256, use adx-environment==0.1.0rc2, and align src/agent-dx with the artifact source. Package contracts reject mismatched builds, mutable URLs and invalid checksums.

Fixes #105
Fixes #107

Consolidates #106. The server/SDK fixes are merged in ADX #69.

Release provenance:

• Source/tag: b208c40964934ba24e04e80136d9f077bddb44f5 / v0.1.0rc2, containing merged ADX fix(sdk): make sandbox cleanup synchronous and best-effort #69. Buildkite #173 passed AMD64/ARM64 native builds, immutable OBS release publication, images and Kubernetes L0/auth/cleanup. Its original PyPI step lacked credentials; SDK Buildkite #13 published the original tested wheel/sdist to PyPI and verified identical hashes.
• Downloaded both architecture release/Execd archives and verified SHA-256, commit/build identity, ELF architecture and embedded SDK hashes against the public manifests. The PyPI wheel/sdist match the same candidate; AKernel pins the AMD64 archives.

Validation at 082f7dd6074a85866d0afcf9a1d146cf8b51e7b0:

• RC2 artifacts are mirrored at agent-dx OBS. All 26 artifact SHA-256/size pairs and 7 manifest/index objects were verified publicly; the original source commit, build identity and hashes are preserved. Both Dockerfile pins use this bucket with unchanged checksums.
• Full GitHub CI passed: Python 3.10–3.14, SDK lint/type checks, clean wheel/sdist installation, deployment helpers and release/deployment contracts. The package contract suite includes 18 passing tests.
• The real all-in-one build log confirms RC2 Platform/Execd downloads from the new bucket. The runsc image passed 10 examples, 7 integration tests and all 30 standalone tests. One additional OCI/Nydus private-write test skipped because AKERNEL_TEST_IMAGE was unset. All 20 tunnel recovery probes completed within 10 seconds; maximum 3.942 seconds. Standalone teardown passed. Docker Hub publication is skipped for PRs.

[rcyw]

Review of 082f7dd6074a85866d0afcf9a1d146cf8b51e7b0: I found one P1 to resolve before merging the ADX 0.1.0rc2 dependency update. The targeted fixes for #105 and #107 look consistent with their intended contracts; the finding concerns another behavior brought in by the dependency update.

P1: ordinary tenant callers can request arbitrary writable Local mounts

The previous ADX revision (af7d82f04a52d4604ea7ca4c550f09c6114dee4d) explicitly rejected public host_path mounts. In the new pinned revision, contract.rs:465-477 accepts an absolute path after lexical validation and turns it into StorageSource::Local, preserving caller-supplied mount options. This helper has no caller context. The public create route does not restrict Local mounts to administrators or enforce a tenant-specific source directory before preparing the request.

Offline reproduction: I built a small probe against this exact ADX revision and called the real public create_spec with CallerContext { tenant_id: "review-tenant-a", administrator: false }. All three source strings below were accepted as Local mounts, with ["rw"] and the caller's tenant preserved:

• /
• /mnt/sfs/workspaces/review-tenant-b
• /var/lib/review-only-not-created

The parser-only input shape was:

{
  "image": "review-fixture:unused",
  "mounts": [
    {"type": "bind", "host_path": "/", "target": "/review-mount", "options": ["rw"]}
  ]
}

Verification boundary: the probe performed contract conversion only. It did not read, create, or mount any of these paths, pull an image, start a sandbox, or access a cluster. This confirms request acceptance, rather than claiming a live filesystem-access exploit.

Source inspection establishes the downstream consequence: ADXlet forwards Local sources and options directly as sandboxd HostPath mounts, and the sandboxd revision pinned by AKernel writes them into the OCI mount specification. Keeping the correct tenant_id on the environment does not authorize its mount source. An ordinary tenant can therefore request writable access to paths visible to the node runtime, including other tenants' storage where present. SDK-side type restrictions do not protect the raw HTTP API.

The new ADX Local mount contract explicitly leaves per-tenant path authorization to the deployment and requires restricting this capability to trusted management callers. AKernel's current public creation path does not implement that boundary.

Requested change: restore default rejection of Local mounts on public creation, or add explicit server-side management authorization and source-path/tenant restrictions before enabling them. Add negative coverage for non-admin callers, both host_path/hostPath spellings, and writable mounts. If the correction requires repackaging ADX, publish a new immutable version and align the platform/Execd archives, checksums, SDK dependency, and gitlink rather than replacing rc2 artifacts.

Checks completed

• AKernel SDK: 301 unit tests and 35 benchmark-harness tests passed; Ruff and mypy passed.
• Published adx-environment==0.1.0rc2: 10 targeted tests passed; its 21 package source/typing files match the pinned source. Six additional offline JSON/SSE probes through the real AKernel constructor confirmed public error fields/cause and terminal-versus-unknown retry behavior.
• ADX Rust: 414 passed, 0 failed, 98 ignored; 97 ignored tests require isolated Redis/related services and one is a release benchmark.
• Runtime/Helm/Terraform contracts: 18/27/3 passed. Both archives at the new agent-dx OBS URLs were downloaded and verified against the pinned SHA-256 values and embedded release metadata. Latest-head CI, including Standalone E2E, passed.

These checks support the #105/#107 fixes but do not cover the missing Local-source authorization. No product code, cloud resources, or cluster deployment was changed during this review.

[WenYuLuo]

@rcyw Thanks for the review. We confirmed that AKernel's public SDK at 082f7dd6074a85866d0afcf9a1d146cf8b51e7b0 already exposes only read-only Image/S3 mounts; it has no Local/HostPath source, writable mount options, or create_if_missing. We will keep Local/HostPath out of the AKernel SDK for now.

The server-side finding remains valid: raw HTTP requests can bypass those SDK restrictions. We are tracking the authorization correction separately in #110, which will remain open as follow-up work. Its acceptance criteria include the public/internal trust boundary, negative authorization coverage, immutable ADX release/dependency updates if needed, and joint E2E regression. This scope decision does not mean the server-side gap is fixed or mitigated by the SDK restriction; #108 will not close #110.

[rcyw]

Approving reviewed head 082f7dd6074a85866d0afcf9a1d146cf8b51e7b0 for integration into develop, following the explicit decision to accept the scoped #105/#107 fixes and track the Local/HostPath authorization correction separately in #110.

The P1 finding in the earlier review remains valid: raw HTTP callers can bypass the public SDK's Image/S3-only mount surface. The SDK restriction does not resolve or mitigate that service-side gap. #110 must stay open until the server-side authorization correction and its regression evidence are complete.

The reviewed source is unchanged, the relevant local checks passed with the previously documented Redis-dependent exclusions, and all current CI checks passed, including Standalone E2E. This approval records acceptance of the documented scope for develop integration; the unresolved Local mount authorization remains tracked as follow-up work.