refactor: migrate to ceres application/transport paths and centralize HTTP errors (#2139)

* refactor: enforce DTO boundaries and extract jupiter-migrate for faster builds

Move mono HTTP DTOs into ceres/model (admin, webhook, bot, note, group) and
route label/group logic through MonoApiService facades so mono no longer
imports jupiter::model. Add CI guard for the DTO boundary, document the
three-layer model rules in ceres/README, and relocate ProtocolError HTTP
mapping to mono.

Extract SeaORM migrations into jupiter-migrate with optional jupiter/migrate
feature gating, fold context into mono/bootstrap, and slim common by
removing axum. Update mono routers, storage init, and workspace deps
accordingly.

* update docs

* refactor: thin mono routers with MonoAppServices facades and ceres domain modules

Introduce MonoAppServices and TransportContext so mono routers stop calling
storage directly, and split MonoApiService into domain modules (user, issue,
conversation, code review, gpg, note, reviewer, cl_list, etc.). Move
notification dispatch/triggers and webhook admin/delivery into ceres
application, relocate pack helpers to infra, and extend CI guards for
callisto, jupiter::service, transport/application, and router storage access.

* refactor: migrate to ceres application/transport paths and centralize HTTP errors

Deprecate ceres legacy re-exports (api_service, pack, protocol, build_trigger,
code_edit) and switch mono/ceres call sites to application::* and transport::*.
Add typed MegaError variants with shared HTTP status mapping in common, simplify
mono ApiError, and improve Git SSH protocol error handling.

Further thin group/tag/artifacts routers via MonoApiService facades and extend
CI guards to block legacy ceres import paths in mono.

Author: benjamin-747

.github/copilot-instructions.md

@@ -26,13 +26,18 @@ cargo nextest run -p <crate> when suggesting fast local test runs
 
 ## Key Components (Modules)
 
-This is a monorepo containing many components. Some key ones include:
-
-* **`mono` / `ceres` / `jupiter` / `moon`**: These are various services and libraries within the monorepo, primarily written in Rust and TypeScript.
-* **`orion`**: Build orchestration and workspace management.
-* **`saturn`**: Policy and permission management.
-
-**Note**: `scorpio` (FUSE filesystem) has been moved to its own repository at [scorpiofs](https://github.com/web3infra-foundation/scorpiofs).
+| Crate | Role |
+|-------|------|
+| `mono` | Server binary (HTTP REST, Git HTTP/SSH, Swagger) |
+| `ceres` | Domain library: transport, application, HTTP DTOs |
+| `jupiter` / `callisto` | Storage and SeaORM entities |
+| `jupiter-migrate` | Database migrations |
+| `orion` / `orion-server` / `orion-scheduler` | Build orchestration |
+| `saturn` | Cedar policy |
+| `vault` | Crypto and secrets |
+| `moon` | Frontend (TypeScript) |
+
+See [docs/architecture.md](docs/architecture.md) for the full workspace map.
 
 ## Coding style & quality
 

.github/workflows/base.yml

@@ -85,6 +85,45 @@ jobs:
         with:
           shared-key: base-${{ runner.os }}-${{ hashFiles('**/Cargo.lock') }}
           cache-on-failure: true
+      - name: Enforce DTO boundary (mono must not import jupiter::model)
+        run: |
+          if rg -q 'jupiter::model' mono/; then
+            echo "mono must not depend on jupiter::model; use ceres::model and MonoApiService facades"
+            rg 'jupiter::model' mono/
+            exit 1
+          fi
+      - name: Enforce module dependency boundaries
+        run: |
+          if rg -q 'use callisto::' mono/src/; then
+            echo "mono/src must not import callisto directly; use ceres::model and MonoApiService facades"
+            rg 'use callisto::' mono/src/
+            exit 1
+          fi
+          if rg -q 'jupiter::service::' mono/src/; then
+            echo "mono/src must not import jupiter::service directly; use MonoApiService facades"
+            rg 'jupiter::service::' mono/src/
+            exit 1
+          fi
+          if rg -q 'api_service::mono::MonoApiService' ceres/src/transport/; then
+            echo "ceres transport must not depend on MonoApiService"
+            rg 'api_service::mono::MonoApiService' ceres/src/transport/
+            exit 1
+          fi
+          if rg -q 'use crate::(pack|transport)' ceres/src/application/; then
+            echo "ceres application must not import transport/pack directly"
+            rg 'use crate::(pack|transport)' ceres/src/application/
+            exit 1
+          fi
+          if rg --glob '!lfs_router.rs' -q '\.storage\.|_stg\(\)' mono/src/api/router/; then
+            echo "mono routers must use MonoApiService facades, not storage"
+            rg --glob '!lfs_router.rs' '\.storage\.|_stg\(\)' mono/src/api/router/
+            exit 1
+          fi
+          if rg -q 'ceres::(api_service|pack|protocol|build_trigger|code_edit)' mono/; then
+            echo "mono must use ceres::application::* and ceres::transport::* instead of legacy re-exports"
+            rg 'ceres::(api_service|pack|protocol|build_trigger|code_edit)' mono/
+            exit 1
+          fi
       - name: Run cargo clippy
         run: |
           sccache --start-server || true

Cargo.lock

@@ -7,10 +7,10 @@ members = [
   "ceres",
   "clients/orion-client",
   "common",
-  "context",
   "io-orbit",
   "jupiter",
   "jupiter/callisto",
+  "jupiter-migrate",
   "mono",
   "orion",
   "orion-scheduler",
@@ -19,7 +19,6 @@ members = [
   "vault",
 ]
 default-members = ["mono", "orion", "orion-server", "orion-scheduler"]
-exclude = ["tools/artifacts-compose-e2e"]
 resolver = "3"
 
 
@@ -29,15 +28,14 @@ io-orbit = { path = "io-orbit" }
 mono = { path = "mono" }
 common = { path = "common" }
 jupiter = { path = "jupiter" }
+jupiter-migrate = { path = "jupiter-migrate" }
 ceres = { path = "ceres" }
 callisto = { path = "jupiter/callisto" }
 vault = { path = "vault" }
 saturn = { path = "saturn" }
 orion = { path = "orion" }
 orion-client = { path = "clients/orion-client" }
 
-context = { path = "context" }
-
 git-internal = "0.7.6"
 libvault-core = "0.1.0"
 

Cargo.toml

@@ -53,6 +53,12 @@ Mega is evolving toward deeper AI-native capabilities:
 
 To facilitate a rapid deployment and hands-on experience with the Mega service, the following instructions are derived from the project's [documentation](https://github.com/web3infra-foundation/mega/tree/main/docker).
 
+- **Docker demo (recommended):** [docker/README.md](docker/README.md)
+- **Native development:** [docs/development.md](docs/development.md)
+- **Architecture:** [docs/architecture.md](docs/architecture.md)
+
+Related projects: [Libra](https://github.com/web3infra-foundation/libra) (Git-compatible agent client), [ScorpioFS](https://github.com/web3infra-foundation/scorpiofs) (FUSE monorepo mount).
+
 ## Community
 
 Discord Channel - https://discord.gg/HMFuu6pJmQ

README.md

@@ -35,13 +35,18 @@ uuid = { workspace = true, features = ["v4"] }
 reqwest = { workspace = true, features = ["json", "stream"] }
 tokio = { workspace = true, features = ["macros", "rt-multi-thread", "net", "process"] }
 tokio-stream = { workspace = true }
-axum = { workspace = true }
+axum-core = "0.5.6"
 async-recursion = { workspace = true }
 sysinfo = { workspace = true }
 utoipa = { workspace = true }
 regex = { workspace = true }
 tokio-util = { workspace = true }
 rkyv = { workspace = true }
 
+[features]
+migrate = ["jupiter/migrate"]
+
 [dev-dependencies]
+axum = { workspace = true }
+jupiter-migrate = { workspace = true }
 tempfile = { workspace = true }

ceres/Cargo.toml

@@ -8,7 +8,7 @@ Monorepo domain library for Mega: Git transport, REST application logic, and sha
 ceres/src/
 ├── lib.rs
 ├── bus/                    # Transport ↔ application event bus
-├── infra/                  # Shared infrastructure (GitObjectCache)
+├── infra/                  # Shared infrastructure (GitObjectCache, pack streams, decode errors)
 ├── transport/
 │   ├── protocol/           # Smart HTTP/SSH Git protocol
 │   └── pack/               # receive-pack / upload-pack handlers
@@ -20,7 +20,9 @@ ceres/src/
 ├── diff/, merge_checker/, lfs/
 ```
 
-Legacy paths (`ceres::protocol`, `ceres::pack`, `ceres::api_service`, etc.) remain as re-exports in `lib.rs` for compatibility with `mono`.
+`mono` uses `ceres::application::*` and `ceres::transport::*` for domain logic and Git transport.
+
+`axum-core` is confined to `ceres/infra/pack_decode.rs` for `git-internal` pack decode stream errors until upstream accepts `std::io::Error`.
 
 ## Dependency rules
 
@@ -31,6 +33,42 @@ Legacy paths (`ceres::protocol`, `ceres::pack`, `ceres::api_service`, etc.) rema
 | `bus` | Minimal shared types for events | `transport` / `application` implementations |
 | `mono` (binary) | Assembles `TransportRuntime` + injects handlers | — |
 
+## Model boundary
+
+Three DTO layers; keep imports aligned with this table:
+
+| Layer | Crate / path | Role | Consumers |
+|-------|--------------|------|-----------|
+| Wire | `api-model` | mono ↔ orion cross-process protocol (buck2, artifacts, shared pagination wrappers) | `mono`, `orion`, `orion-client`, `ceres` (pagination only where needed) |
+| HTTP / OpenAPI | `ceres/model` | All mono REST request/response types + `utoipa` schemas | `mono` routers, `ceres` application |
+| Storage assembly | `jupiter/model` | Bundles of `callisto` entities from storage/services; no serde/utoipa | `jupiter` storage/service, `ceres` application only |
+
+Rules:
+
+- `mono` routers must **not** `use jupiter::model` — map via `ceres::model` and `MonoApiService` facades.
+- `mono/src` must **not** `use callisto::` or `jupiter::service::` — storage entities and service calls stay in `ceres` application layer.
+- `ceres/src/transport` must **not** reference `MonoApiService` (transport ↔ application boundary).
+- `api-model` is **not** mono HTTP schema (except shared wrappers like `CommonPage` / `Pagination`).
+- `ceres/model` is the mapping hub: `impl From<jupiter::model::*>` and `impl From<callisto::*>` live here.
+- `application/build_trigger/model` is a ceres subdomain API schema (build triggers); same HTTP rules as `ceres/model`, kept alongside orchestration until a later consolidation.
+
+## Error type boundaries
+
+| Layer | Error type | HTTP adapter (mono) |
+|-------|------------|---------------------|
+| `ceres/application`, `jupiter` | `MegaError` | `ApiError` (`mono/src/api/error.rs`) |
+| `ceres/transport`, Git Smart HTTP/SSH | `ProtocolError` | `protocol_error::into_response` |
+| Buck upload | `BuckError` (via `MegaError::Buck`) | `ApiError` |
+| Git LFS | `GitLFSError` | `map_lfs_error` in `lfs_router` |
+
+Rules:
+
+- REST routers and `MonoApiService` use `MegaError` only; `api_handler` resolves import vs mono handlers and returns `MegaError`.
+- `ProtocolError` is confined to Git client protocol paths; use `mega_to_protocol_error` at transport boundaries when mapping domain failures.
+- Do not use `ProtocolError` in REST handlers.
+
+Long term: extract `ceres/model` → `mega-api-types` only if a non-mono consumer needs HTTP DTOs without ceres domain code.
+
 ## Git push event flow
 
 ```mermaid

ceres/README.md

@@ -17,7 +17,7 @@ use git_internal::{
 };
 
 use crate::{
-    api_service::ApiHandler,
+    application::api_service::ApiHandler,
     model::blame::{BlameBlock, BlameInfo, BlameQuery, BlameResult, Contributor},
 };
 
@@ -182,7 +182,8 @@ pub async fn get_file_blame<T: ApiHandler + ?Sized>(
 
     // Resolve starting commit from refs
     let start_commit =
-        crate::api_service::commit_ops::resolve_start_commit(handler, ref_name).await?;
+        crate::application::api_service::commit_ops::resolve_start_commit(handler, ref_name)
+            .await?;
 
     // Get file content and blob hash at start commit
     let (current_content, start_blob_hash) =

ceres/src/application/api_service/blame_ops.rs

@@ -14,7 +14,7 @@ use git_internal::{
 use sha1::{Digest, Sha1};
 
 use crate::{
-    api_service::{ApiHandler, tree_ops},
+    application::api_service::{ApiHandler, tree_ops},
     model::git::DiffPreviewPayload,
 };
 

ceres/src/application/api_service/blob_ops.rs

@@ -21,7 +21,7 @@ use jupiter::redis::AsyncCommands;
 use serde::{Deserialize, Serialize};
 
 use crate::{
-    api_service::{ApiHandler, history, tree_ops},
+    application::api_service::{ApiHandler, history, tree_ops},
     model::{
         change_list::{DiffItemSchema, MuiTreeNode},
         commit::{CommitFilesChangedPage, CommitSummary, GpgStatus},