[earakely-scale]

Summary

put_gateway_env, put_service_db_env and put_website_browser_env take an optional version=. When given, the env is stored as exactly that version, which must be the env's next one. Otherwise the put raises ConcurrentModificationError and writes no env. A version below 1 raises ValueError before anything is written, since the store reads 0 as "the next free version". Without version= they behave as before.

Their metadata is also typed Mapping[str, Any] rather than strings only, as Env.metadata already is. The promotion keeps a record of what it checked, which is a mapping, on the version it writes.

Why

AgentEnvHub is going to promote the gateway and service-db images from each release, as it already does for the agents. A promotion reads default at one version and writes the next. If someone runs agent-env env gateway put in the meantime, the promotion should write nothing and report itself busy, not overwrite what they put. The sdk's put_published already works this way for agents.

Env.put has enforced a named version since #327, so the change only passes version through. As with put_published, the image artifacts are still written first under their own next versions. An env write that loses the race leaves those image versions unreferenced, and nothing reads them.

Testing

• New test_a_put_that_names_a_version_writes_only_that_next_one, for each of the three kinds against local stores. It registers published digests, writes v2 by name, and checks that a second write naming v2 raises and leaves the env at v2.
• New test_a_put_keeps_metadata_that_isnt_a_string.
• New test_a_put_refuses_a_version_below_1_before_writing_anything, for each kind with 0 and -1.
• tst/unit/env/bootstrap_test.py: 45 passed after the last two commits.
• tst/unit/ and packages/agentenv-protocol/tests/: 11,138 passed, 66 skipped.
• ruff check passes.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; the earlier zero-version issue is fixed.

Summary

The three infrastructure env helpers accept an optional version and allow non-string metadata.

• Infra env puts can save promotion details on a named version.

_{Reviews (2) · Last reviewed commit: "fix(env): an infra env put refuses a ver..." · Reviewed by Greptile}