[A3S Cloud/A0] Define an immutable headless Agent release contract

[ZhiXiao-Lin]

Cloud gate

A0 — hosted Agent releases on the common build and Runtime deployment path.

Planning reference: https://github.com/A3S-Lab/Cloud/blob/e2a05b7f1f63486b2fda866b22aa84eea89aadb4/docs/development-plan.md

Problem

Cloud needs to deploy an Agent as an immutable, headless release rather than infer behavior from a mutable local workspace. Code must define the artifact, lifecycle, health, and compatibility contract that the A0 catalog can reference.

Scope

• Define a versioned Agent release manifest with immutable artifact digest, entrypoint, protocol version, required capabilities, health contract, and provenance references.
• Add a headless execution mode with deterministic readiness, liveness, graceful shutdown, and exit semantics.
• Accept secrets only through external references or injected runtime material; never embed them in the release manifest.
• Define writable workspace, cache, and persistent-data boundaries.
• Publish one minimal immutable Agent release fixture for cross-repository deployment tests.
• Document compatibility and breaking-change policy for the release contract.

Acceptance criteria

• The fixture builds once and is deployable by digest as a Runtime Service without an interactive terminal.
• Readiness becomes true only when the Agent can accept work, and shutdown completes within a configured deadline.
• The same manifest and artifact produce the same declared release identity.
• Secret values are absent from the manifest, artifact metadata, logs, and health response.
• Invalid protocol or capability requirements fail before activation with structured diagnostics.

Non-goals

• Implementing Cloud catalog, tenancy, routing, or scheduling in Code.
• Mutable workspace snapshots as release identity.
• A separate deployment lifecycle from ordinary Runtime Services.

[ZhiXiao-Lin]

Status audit (2026-07-19, current main / v6.0.0): the existing serve_agent_dir API is useful infrastructure but does not yet satisfy this A0 release contract.

Evidence from the current implementation:

• core/src/serve/daemon.rs runs cron schedules only; it does not expose a headless Agent request/health protocol.
• Node and Python return ServeHandle immediately after spawning the core future, before schedule sessions and AgentDir tools have finished preparing.
• preparation/runtime failures after that return are written to stderr and are not reflected as deterministic readiness or a typed terminal status.
• ServeHandle.stop() only signals the cancellation token; it does not join the daemon or prove bounded completion by a shutdown deadline.
• there is no release manifest, readiness/liveness contract, immutable artifact identity, or pre-activation protocol/capability matcher on main.

The Cloud A0 plan also names .a3s/asset.acl as the release manifest boundary. Canonical ACL type stability and bounded untrusted parsing are currently awaiting human review in A3S-Lab/ACL#3 and A3S-Lab/ACL#4, so defining a supposedly immutable Code identity against a different ad hoc serialization would create a cross-repository guarantee that the owning format does not yet provide.

Keep this issue open. A safe sequence is: land the ACL canonical/admission prerequisites, define the versioned Agent ACL schema and canonical identity, then make daemon preparation observable and make stop await a bounded terminal state before certifying a minimal Runtime Service fixture. No release, tag, or production activation was performed in this audit.

[ZhiXiao-Lin]

Dependency update (2026-07-20): the ACL admission prerequisite identified in the earlier audit has now landed. ACL #9 merged as 63f3cd7, and a3s #33 synchronized that revision into the Cloud compatibility lock and bilingual API documentation.

Code can now define a trusted .a3s/asset.acl schema with closed-by-default attributes/blocks, recursive value and call rules, stable redacted diagnostics, bounded admission, and canonical bytes/digests without inventing a parallel parser or serializer. Both upstream post-merge CI and the synchronized Cloud Stack/docs workflows are green.

Keep this issue open. The Code-owned work remains: define the versioned release manifest and immutable identity, make daemon preparation/readiness observable, implement liveness and bounded graceful shutdown semantics, certify secret/workspace boundaries, and publish the cross-repository Runtime Service fixture.

[ZhiXiao-Lin]

Immutable-identity prerequisite update (2026-07-20): schema-defined normalization for semantically unordered ACL blocks has now landed in ACL #10 as 00ef948, and a3s #34 synchronized it into the Cloud compatibility lock and bilingual API documentation as d17d265.

A future trusted .a3s/asset.acl release schema can now mark only genuinely set-like repeated block types as unordered and derive identity with the schema-aware canonical digest APIs. Reordering those same-name occurrences cannot change the digest, while unrelated, unknown, labeled, list, call, and unmarked constructs retain ordered semantics. Admission remains explicit and separate from normalization. The shared Rust/Node corpus covers recursive, interleaved, empty, unknown, and 1,000-block adversarial cases; upstream and synchronized post-merge CI are green.

Keep this issue open. Code still owns the versioned release schema and fixture, artifact/provenance binding, observable readiness and liveness, bounded graceful shutdown, secret/workspace boundaries, and pre-activation Runtime capability checks.

[ZhiXiao-Lin]

Contract/admission slice landed in Code #18 as eff4b88. Remote Linux, Windows, and SDK CI all passed.

Evidence now on main:

• .a3s/asset.acl has a closed, bounded a3s.code.agent-release.v1 schema covering an immutable lowercase OCI digest/media type, static entrypoint, independently versioned Agent protocol, HTTP health/shutdown declaration, explicit workspace/cache/persistent-data modes, typed capability requirements, typed external-secret injection slots, and digest-bound provenance.
• AgentReleaseManifest performs bounded ACL admission, semantic validation, schema-aware canonicalization, and SHA-256 identity derivation. capability, secret, and provenance blocks are schema-declared unordered sets; ordered entrypoint arguments retain order.
• The contract fixture has pinned identity sha256:18a6f165a9dce546db0cc61402f9a55d9be138e5f4e52a7649e0935c51bd504b. Tests prove formatting/set-order equivalence, round-trip stability, artifact mutation changing identity, bounded file input, closed schema behavior, and duplicate rejection.
• Pre-activation compatibility requires an exact protocol match and at least each declared capability level. Failures use stable incompatible_protocol / unsupported_capability codes and value-redacting structural diagnostics.
• Secret declarations contain only a slot name and either a POSIX environment destination or canonical /run/secrets/ path. Names and injection destinations are unique; secret values and external identifiers have no manifest field, attempted extra/value fields fail closed, and errors do not echo manifest values.
• manual/AGENT_RELEASE_CONTRACT.md documents field limits, identity semantics, secret/storage boundaries, compatibility, and breaking-change policy.

Keep this issue open. The checked-in fixture intentionally uses placeholder OCI/provenance digests and is a parser/identity fixture, not a deployable release. Remaining acceptance work is observable daemon preparation and request serving, real readiness/liveness behavior, joined shutdown within the configured deadline, a real immutable image build, end-to-end external secret injection with artifact/log/health redaction evidence, Runtime Service deployment by digest, and cross-repository A0 certification.