feat(cloud): lock reproducible integration stack (#29)

Co-authored-by: Roy Lin <roylin@a3s.dev>

Author: ZhiXiao-Lin

.github/workflows/cloud-stack.yml

@@ -0,0 +1,98 @@
+name: Cloud Stack
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/cloud-stack.yml"
+      - ".gitmodules"
+      - "apps/cloud"
+      - "compat/**"
+      - "crates/acl"
+      - "crates/boot"
+      - "crates/event"
+      - "crates/flow"
+      - "crates/gateway"
+      - "crates/orm"
+      - "crates/runtime"
+      - "crates/sentry"
+      - "crates/updater/**"
+      - "justfile"
+      - "scripts/verify-cloud-stack.mjs"
+      - "scripts/verify-cloud-stack.test.mjs"
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/cloud-stack.yml"
+      - ".gitmodules"
+      - "apps/cloud"
+      - "compat/**"
+      - "crates/acl"
+      - "crates/boot"
+      - "crates/event"
+      - "crates/flow"
+      - "crates/gateway"
+      - "crates/orm"
+      - "crates/runtime"
+      - "crates/sentry"
+      - "crates/updater/**"
+      - "justfile"
+      - "scripts/verify-cloud-stack.mjs"
+      - "scripts/verify-cloud-stack.test.mjs"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: cloud-stack-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    name: Locked stack and contracts
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout orchestrator
+        uses: actions/checkout@v4
+
+      - name: Initialize locked integration inputs
+        run: |
+          git config --global url."https://github.com/".insteadOf "git@github.com:"
+          git submodule update --init -- \
+            apps/cloud \
+            crates/acl \
+            crates/boot \
+            crates/event \
+            crates/flow \
+            crates/gateway \
+            crates/orm \
+            crates/runtime \
+            crates/sentry
+
+      - name: Install Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install Rust 1.88.0
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: "1.88.0"
+
+      - name: Test compatibility-lock policy
+        run: node --test scripts/verify-cloud-stack.test.mjs
+
+      - name: Print and verify exact integration inputs
+        run: node scripts/verify-cloud-stack.mjs
+
+      - name: Resolve locked Cloud metadata
+        run: cargo metadata --manifest-path apps/cloud/Cargo.toml --locked --format-version 1
+
+      - name: Build the locked Cloud workspace
+        run: cargo check --manifest-path apps/cloud/Cargo.toml --workspace --all-targets --locked
+
+      - name: Run Cloud contract fixtures
+        run: cargo test --manifest-path apps/cloud/Cargo.toml --locked -p a3s-cloud-contracts
+
+      - name: Check the locked Gateway dependency surface
+        run: cargo check --manifest-path crates/gateway/Cargo.toml --locked --all-targets --features wire

.gitmodules

@@ -55,12 +55,21 @@
 [submodule "apps/desktop"]
 	path = apps/desktop
 	url = git@github.com:A3S-Lab/Desktop.git
+[submodule "apps/cloud"]
+	path = apps/cloud
+	url = git@github.com:A3S-Lab/Cloud.git
 [submodule "crates/flow"]
 	path = crates/flow
 	url = git@github.com:A3S-Lab/Flow.git
 [submodule "crates/boot"]
 	path = crates/boot
 	url = git@github.com:A3S-Lab/Boot.git
+[submodule "crates/runtime"]
+	path = crates/runtime
+	url = git@github.com:A3S-Lab/Runtime.git
+[submodule "crates/orm"]
+	path = crates/orm
+	url = git@github.com:A3S-Lab/ORM.git
 [submodule "crates/use"]
 	path = crates/use
 	url = git@github.com:A3S-Lab/Use.git

AGENTS.md

@@ -9,10 +9,12 @@ This file provides repository guidance for Codex and other coding agents working
 ```text
 a3s/
 ├── apps/
+│   ├── cloud/        # Cloud control plane and node agent (submodule)
 │   └── docs/         # Documentation site
 ├── crates/           # Rust crates as submodules
-│   ├── acl/ ahp/ box/ code/ event/ gateway/
-│   ├── lane/ memory/ power/ search/ updater/ use/
+│   ├── acl/ ahp/ box/ code/ event/ flow/ gateway/
+│   ├── lane/ memory/ orm/ power/ runtime/ search/ use/
+│   ├── updater/      # Root-owned shared crate
 │   └── common/       # Shared types (local crate)
 └── homebrew-tap/     # Homebrew tap
 ```
@@ -87,6 +89,19 @@ Conventions:
 - ACL means the A3S Agent Configuration Language. Parse and generate it with
   `a3s-acl`; do not treat ACL as HCL or use an HCL parser for ACL files.
 
+## Cloud Compatibility Lock
+
+- `compat/cloud-stack.acl` is the source of truth for Cloud integration
+  revisions, package versions, ownership, and protocol levels.
+- Keep component and protocol blocks sorted and keep the file in the canonical
+  form generated by the checked-in `a3s-acl` Node SDK.
+- Update a component's gitlink, exact Cargo dependency, and lock entry together.
+- Run `just cloud-stack-check` from a clean checkout with the locked Cloud,
+  ACL, Boot, Event, Flow, Gateway, ORM, Runtime, and Sentry submodules
+  initialized.
+- Do not publish a compatibility update until the lock verifier and Cloud
+  contract fixtures pass.
+
 ## NestJS And DDD Rules
 
 Every business module must follow the four-layer DDD structure:
@@ -254,4 +269,5 @@ Rules:
 - Removed dead wrappers, orphaned exports, and redundant modules.
 - Used typed extension options where applicable.
 - Updated documentation for completed features.
+- Updated and verified `compat/cloud-stack.acl` for Cloud integration changes.
 - Ran formatting and relevant checks/tests from the correct workspace or app.

README.md

@@ -34,11 +34,11 @@ is Rust.
 
 | Area | Paths | Purpose |
 | --- | --- | --- |
-| Product surfaces | `crates/cli`, `crates/bench`, `apps/web`, `apps/box`, `apps/docs` | CLI, browser workspace, benchmark control component, native app, and documentation site. |
+| Product surfaces | `crates/cli`, `crates/bench`, `apps/web`, `apps/box`, `apps/cloud`, `apps/docs` | CLI, browser workspace, benchmark control component, native app, Cloud control plane, and documentation site. |
 | Agent runtime | `crates/code`, `crates/ahp`, `crates/acl`, `crates/common` | Sessions, tools, policy, protocol, config, and shared types. |
 | UI systems | `crates/tui`, `crates/gui`, `crates/webview` | Terminal UI, native RSX UI, and trusted WebView helpers. |
 | Use and retrieval | `crates/use`, `crates/search` | Browser, native Office, and OCR capability surfaces, external Use extensions, and search through the shared Browser runtime. |
-| State and coordination | `crates/memory`, `crates/event`, `crates/flow`, `crates/lane` | Memory, events, workflows, and queues. |
+| State and coordination | `crates/memory`, `crates/event`, `crates/flow`, `crates/lane`, `crates/orm` | Memory, events, workflows, queues, and typed persistence. |
 | Runtime safety and operations | `crates/runtime`, `crates/box`, `crates/observer`, `crates/sentry` | Provider-neutral execution, isolation, observability, and runtime control. |
 | Services | `crates/boot`, `crates/gateway`, `crates/power` | Service framework, ingress, and model serving. |
 | Distribution | `crates/updater`, `homebrew-tap` | CLI self-update support and Homebrew formulae. |
@@ -49,26 +49,28 @@ is Rust.
 | --- | --- | --- |
 | [A3S Web](apps/web/) | 0.1.0 | Browser workspace for the A3S Code product, served by the local CLI. |
 | [A3S Box Desktop](apps/box/) | 0.1.0 | Native A3S Box management client. |
+| [A3S Cloud](apps/cloud/) | 0.1.0 | Multi-tenant control plane, node agent, and versioned Cloud contracts. |
 | [a3s](crates/cli/) | 0.9.1 | End-user CLI and typed component-management entrypoint. |
 | [a3s-code](crates/code/) | core and SDKs 5.3.1 | Rust agent runtime plus Node and Python SDK bindings. |
 | [a3s-gui](crates/gui/) | 0.1.0 | Native GUI runtime with hooks, RSX templates, semantic UI, and platform hosts. |
 | [a3s-tui](crates/tui/) | 0.1.10 | Terminal UI framework used by `a3s code`. |
 | [a3s-flow](crates/flow/) | 0.4.1 | Durable workflow engine with event-sourced runs and replay. |
+| [a3s-orm](crates/orm/) | 0.1.0 | Typed SQL, migrations, and PostgreSQL/SQLite persistence. |
 | [a3s-memory](crates/memory/) | 0.1.2 | Pluggable long-term memory storage for agents. |
 | [a3s-event](crates/event/) | 0.3.0 | Event subscription, dispatch, and persistence. |
 | [a3s-lane](crates/lane/) | 0.5.0 | Rust-only priority and job queue with Redis, flows, repeat jobs, worker leases, retry, and DLQ. |
 | [a3s-use](crates/use/) | 0.1.1 | Typed Browser, native Office, and OCR capability layer plus native CLI, standard MCP, and Skill extension surfaces. |
 | [a3s-search](crates/search/) | 1.4.3 | Embeddable meta-search engine using `a3s-use-browser` for headless browsing. |
 | [a3s-bench](crates/bench/) | 0.1.0 | Reproducible evaluation of coding agents, automated systems, and deterministic tools. |
-| [a3s-runtime](crates/runtime/) | 0.1.0 | Provider-neutral execution contract and Runtime client. |
+| [a3s-runtime](crates/runtime/) | 0.2.0 | Provider-neutral execution contract and Runtime client. |
 | [a3s-box](crates/box/) | 3.0.5 | Docker-like MicroVM runtime for Linux OCI workloads. |
 | [a3s-observer](crates/observer/) | 0.11.0 | eBPF observability for LLM calls, tools, files, and egress. |
-| [a3s-sentry](crates/sentry/) | 0.6.0 | Tiered runtime security control. |
-| [a3s-boot](crates/boot/) | 0.1.0 | Nest-inspired modular service framework for Rust APIs. |
-| [a3s-gateway](crates/gateway/) | 1.0.11 | Reverse proxy, routing, middleware, streaming, and scale-to-zero. |
+| [a3s-sentry](crates/sentry/) | 0.7.0 | Tiered runtime security control. |
+| [a3s-boot](crates/boot/) | 0.1.1 | Nest-inspired modular service framework for Rust APIs. |
+| [a3s-gateway](crates/gateway/) | 1.0.12 | Reverse proxy, routing, middleware, streaming, and scale-to-zero. |
 | [a3s-power](crates/power/) | 0.4.2 | Privacy-preserving LLM inference for TEE environments. |
 | [a3s-ahp](crates/ahp/) | 2.4.0 | Agent Harness Protocol supervision primitives. |
-| [a3s-acl](crates/acl/) | 0.2.1 | Agent Configuration Language parser. |
+| [a3s-acl](crates/acl/) | 0.2.2 | Agent Configuration Language parser. |
 | [a3s-webview](crates/webview/) | 0.1.1 | Native trusted WebView popup helper. |
 | [a3s-common](crates/common/) | 0.1.1 | Shared primitives and transport types. |
 | [a3s-updater](crates/updater/) | 0.3.0 | Verified component transactions and self-update support for CLI binaries. |
@@ -154,6 +156,9 @@ Local development:
 ```bash
 git submodule update --init --recursive
 
+# Verify the exact Cloud integration stack and contract fixtures.
+just cloud-stack-check
+
 # Run A3S Code from source.
 just code
 
@@ -205,7 +210,12 @@ git commit -m "Update <component> snapshot"
 
 Applications under `apps/` use app-local workflows. The root `justfile` only
 orchestrates common entry points such as `just code`, `just dev`, `just web`,
-`just use-hotplug-e2e`, and `just box-check`.
+`just use-hotplug-e2e`, and `just cloud-stack-check`.
+
+Cloud integration revisions and protocol levels are recorded in
+`compat/cloud-stack.acl`. Update that ACL lock and the corresponding gitlinks
+together; its verifier rejects missing, dirty, or mismatched inputs before the
+cross-repository contract gate runs.
 
 ## Documentation
 

apps/cloud

@@ -0,0 +1,33 @@
+# Cloud Stack Compatibility Lock
+
+`cloud-stack.acl` is the machine-readable compatibility boundary for the A3S
+Cloud integration gate. It pins every participating submodule to a full commit,
+records exact Cargo package versions, and names the protocol levels exercised
+by the gate. The root-owned Updater crate is pinned by its exact package version
+and by the root commit that contains it.
+
+The lock is parsed and regenerated with the checked-in `a3s-acl` Node SDK.
+`node scripts/verify-cloud-stack.mjs` rejects non-canonical ACL, unknown fields,
+unsafe or duplicate paths, missing gitlinks, unexpected submodule URLs,
+revision drift, dirty component worktrees, Cargo manifest or lockfile drift,
+and mismatched Cloud or Gateway dependencies. It also parses and generates all
+tracked Cloud product-configuration fixtures and rejects HCL/Terraform product
+configuration in the Cloud integration surface.
+
+## Proposing An Update
+
+1. Update the component in its own repository and obtain an immutable release
+   or full commit revision.
+2. Update the root submodule gitlink and the corresponding `component` block.
+   Keep component and protocol blocks sorted by label, and keep attributes in
+   the order produced by `a3s-acl`.
+3. Update exact dependency declarations and Cargo lockfiles in the owning
+   component repository before moving its root gitlink.
+4. Run `just cloud-stack-check` from a clean recursive checkout.
+5. Include the printed compatibility-lock digest and component revisions in
+   the pull request evidence. Do not publish the compatibility update until the
+   Cloud contract gate passes.
+
+The compatibility lock does not replace component release processes. A lock
+change is integration evidence: each component still owns its implementation,
+tests, release notes, and publication.

compat/README.md

@@ -0,0 +1,129 @@
+stack "cloud" {
+  format = 1
+  owner = "A3S-Lab/Cloud"
+  rust_version = "1.88.0"
+  schema = "a3s.cloud.compatibility-lock.v1"
+}
+component "acl" {
+  owner = "A3S-Lab/ACL"
+  package = "a3s-acl"
+  path = "crates/acl"
+  repository = "git@github.com:A3S-Lab/ACL.git"
+  revision = "ef6fde1614313c14a13a543d37be014eb362776d"
+  source = "git"
+  version = "0.2.2"
+}
+component "boot" {
+  owner = "A3S-Lab/Boot"
+  package = "a3s-boot"
+  path = "crates/boot"
+  repository = "git@github.com:A3S-Lab/Boot.git"
+  revision = "aed8a8b213b1675f4c0b6d5a59599fb9fe9a0249"
+  source = "git"
+  version = "0.1.1"
+}
+component "cloud" {
+  owner = "A3S-Lab/Cloud"
+  path = "apps/cloud"
+  repository = "git@github.com:A3S-Lab/Cloud.git"
+  revision = "85f5d13104e5129a3b9be3f46456b5cb0099ba77"
+  source = "git"
+  version = "0.1.0"
+}
+component "event" {
+  owner = "A3S-Lab/Event"
+  package = "a3s-event"
+  path = "crates/event"
+  repository = "git@github.com:A3S-Lab/Event.git"
+  revision = "6df3d6551a2a3ab68b2f8271d33a87b078fc8151"
+  source = "git"
+  version = "0.3.0"
+}
+component "flow" {
+  owner = "A3S-Lab/Flow"
+  package = "a3s-flow"
+  path = "crates/flow"
+  repository = "git@github.com:A3S-Lab/Flow.git"
+  revision = "d11cc9ab1e859b23c5108882158ade8d296d93ab"
+  source = "git"
+  version = "0.4.1"
+}
+component "gateway" {
+  owner = "A3S-Lab/Gateway"
+  package = "a3s-gateway"
+  path = "crates/gateway"
+  repository = "git@github.com:A3S-Lab/Gateway.git"
+  revision = "d20c6eb22628d80c21daa5de42b362a768d99946"
+  source = "git"
+  version = "1.0.12"
+}
+component "orm" {
+  owner = "A3S-Lab/ORM"
+  package = "a3s-orm"
+  path = "crates/orm"
+  repository = "git@github.com:A3S-Lab/ORM.git"
+  revision = "6fdeae38032a5134e858cf3985f47d60cb5180ac"
+  source = "git"
+  version = "0.1.0"
+}
+component "runtime" {
+  owner = "A3S-Lab/Runtime"
+  package = "a3s-runtime"
+  path = "crates/runtime"
+  repository = "git@github.com:A3S-Lab/Runtime.git"
+  revision = "010588fc36c850b5ef86f1847c0a0e976f1eda82"
+  source = "git"
+  version = "0.2.0"
+}
+component "sentry" {
+  owner = "A3S-Lab/Sentry"
+  package = "a3s-sentry"
+  path = "crates/sentry"
+  repository = "git@github.com:A3S-Lab/Sentry.git"
+  revision = "cf93cc28ffe49e6b97d0197da778db923cb4a72f"
+  source = "git"
+  version = "0.7.0"
+}
+component "updater" {
+  owner = "A3S-Lab/a3s"
+  package = "a3s-updater"
+  path = "crates/updater"
+  source = "workspace"
+  version = "0.3.0"
+}
+protocol "cloud-gateway-snapshot" {
+  level = 2
+  owner = "A3S-Lab/Cloud"
+  schema = "a3s.cloud.gateway-snapshot.v2"
+  source = "apps/cloud/crates/contracts/src/node/gateway.rs"
+}
+protocol "cloud-node-command" {
+  level = 1
+  owner = "A3S-Lab/Cloud"
+  schema = "a3s.cloud.node-command.v1"
+  source = "apps/cloud/crates/contracts/src/node/command.rs"
+}
+protocol "flow-native-typescript" {
+  level = 1
+  owner = "A3S-Lab/Flow"
+  schema = "a3s.flow.native_ts.v1"
+  source = "crates/flow/src/protocol.rs"
+}
+protocol "runtime-capabilities" {
+  level = 3
+  owner = "A3S-Lab/Runtime"
+  schema = "a3s.runtime.capabilities.v3"
+  source = "crates/runtime/src/contract/capabilities.rs"
+}
+protocol "runtime-observation" {
+  level = 2
+  owner = "A3S-Lab/Runtime"
+  schema = "a3s.runtime.observation.v2"
+  source = "crates/runtime/src/contract/observation.rs"
+}
+protocol "runtime-unit-spec" {
+  level = 2
+  owner = "A3S-Lab/Runtime"
+  schema = "a3s.runtime.unit-spec.v2"
+  source = "crates/runtime/src/contract/unit.rs"
+}