docs(clob): Phase 0 protocol spec, legacy archive point, and CI restore (#877-#879, #530)

.github/workflows/ci.yml

@@ -0,0 +1,149 @@
+name: CI
+
+# Core build/test gate (#1057). Runs on every PR into main and every push to
+# main: two individually-green PRs can still combine into a broken main, and a
+# broken main must leave a visible failing run. Replaces lint.yml + test.yml.
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.ref }}
+  # Supersede stale PR runs, but never cancel a run on main: every push to
+  # main must finish with a pass/fail result.
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  fmt:
+    name: rustfmt
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust stable + rustfmt
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+
+      - name: cargo fmt --check
+        run: cargo fmt --all -- --check
+
+  clippy:
+    name: clippy (all targets)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust stable + clippy + wasm32v1-none
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+          # tests/router_and_factory_coverage.rs embeds market_token.wasm.
+          targets: wasm32v1-none
+
+      - name: Cache Cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-clippy-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-clippy-
+
+      - name: Build WASM fixtures used by tests
+        run: make test-wasm
+
+      # --all-targets: without it, #[cfg(test)] modules and tests/ are never
+      # compiled, and test code silently rots while lint stays green.
+      - name: cargo clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+
+  build:
+    name: build contracts (wasm32v1-none)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust stable + wasm32v1-none
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32v1-none
+
+      - name: Cache Cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-wasm-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-wasm-
+
+      # Every contract in mx/common.mk CONTRACTS, for the deploy target.
+      # Contract-macro limits (e.g. 32-char function names) are only enforced
+      # here, not by `cargo check` / `cargo test`.
+      - name: Build deployable contracts
+        run: make build-wasm
+
+  test:
+    name: cargo test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust stable + wasm32v1-none
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32v1-none
+
+      - name: Cache Cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-test-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-test-
+
+      # Builds the WASM fixtures, then `cargo test --workspace`. A test target
+      # that fails to compile or a failing test fails this job.
+      - name: make test
+        run: make test
+
+  # Single status to mark as required in branch protection: it is red unless
+  # every job above succeeded (a skipped or cancelled job counts as failure).
+  ci-passed:
+    name: CI passed
+    if: always()
+    needs: [fmt, clippy, build, test]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require every CI job to succeed
+        env:
+          RESULTS: ${{ join(needs.*.result, ' ') }}
+        run: |
+          echo "job results: $RESULTS"
+          for r in $RESULTS; do
+            if [ "$r" != "success" ]; then
+              echo "::error::a required CI job finished with '$r'"
+              exit 1
+            fi
+          done

docs/legacy-archive.md

@@ -0,0 +1,21 @@
+# Legacy GMX-Style Implementation
+
+The GMX-style synthetic order-book DEX was retired when the repository was reset for the SO4 CLOB
+rewrite. Active development follows the CLOB architecture in [protocol.md](protocol.md). The legacy
+code is not part of `main` and must not be merged back into it.
+
+| Item | Value |
+|------|-------|
+| Archive branch | `gmx-synthetic-order-book-dex` |
+| Archive point | `5436392dcfdfdeb3a8f4d7724a73031d6aeee8c3` (`Merge pull request #1088`) |
+| Reset merged by | `280f268` (`Merge pull request #1090`) |
+
+The archive point is the last `main` commit before the reset. The archive branch points at that
+commit and holds the full legacy tree: contracts, scripts, tests, docs, and `.github/` workflows.
+
+To inspect the legacy implementation:
+
+```bash
+git fetch origin
+git checkout gmx-synthetic-order-book-dex
+```