PerryTS · TheHypnoo · Jul 22, 2026 · Jul 22, 2026 · Jul 22, 2026 · Jul 22, 2026
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
@@ -48,46 +48,23 @@ jobs:
           tool: cargo-llvm-cov
 
       - name: Run coverage
-        # Mirrors the `cargo-test` job's exclude list (host-only UI
-        # backends). `--no-fail-fast` keeps the
+        # Uses the same centralized Linux test scope as `cargo-test`.
+        # `--no-fail-fast` keeps the
         # report comprehensive even if one crate's tests fail —
         # this is a visibility job, not a gate.
         run: |
+          mapfile -t excluded < <(python3 scripts/workspace_architecture.py \
+            --print-excluded-scope linux-test)
+          exclude_args=()
+          for package in "${excluded[@]}"; do exclude_args+=(--exclude "$package"); done
           cargo llvm-cov --workspace --no-fail-fast \
-            --exclude perry-doc-fixture-my-bindings \
-            --exclude perry-ui-macos \
-            --exclude perry-ui-ios \
-            --exclude perry-ui-visionos \
-            --exclude perry-ui-tvos \
-            --exclude perry-ui-watchos \
-            --exclude perry-ui-gtk4 \
-            --exclude perry-ui-android \
-            --exclude perry-ui-windows \
-            --exclude perry-ui-windows-winui \
+            "${exclude_args[@]}" \
             --html --output-dir target/llvm-cov-html
           cargo llvm-cov report --no-fail-fast \
-            --exclude perry-doc-fixture-my-bindings \
-            --exclude perry-ui-macos \
-            --exclude perry-ui-ios \
-            --exclude perry-ui-visionos \
-            --exclude perry-ui-tvos \
-            --exclude perry-ui-watchos \
-            --exclude perry-ui-gtk4 \
-            --exclude perry-ui-android \
-            --exclude perry-ui-windows \
-            --exclude perry-ui-windows-winui \
+            "${exclude_args[@]}" \
             --lcov --output-path target/lcov.info
           cargo llvm-cov report --no-fail-fast \
-            --exclude perry-doc-fixture-my-bindings \
-            --exclude perry-ui-macos \
-            --exclude perry-ui-ios \
-            --exclude perry-ui-visionos \
-            --exclude perry-ui-tvos \
-            --exclude perry-ui-watchos \
-            --exclude perry-ui-gtk4 \
-            --exclude perry-ui-android \
-            --exclude perry-ui-windows \
-            --exclude perry-ui-windows-winui \
+            "${exclude_args[@]}" \
             --summary-only > target/summary.txt
         # Don't fail the workflow on a non-zero exit — the artifacts
         # below are still useful, and a missing test in one crate

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -126,6 +126,11 @@ jobs:
       - name: Check formatting
         run: cargo fmt --all -- --check
 
+      - name: Audit workspace architecture
+        run: |
+          python3 scripts/workspace_architecture.py --self-test
+          python3 scripts/workspace_architecture.py --check --print-summary
+
       - name: Public benchmark evidence freshness
         run: |
           PYTHONPATH=. python3 tests/test_public_baseline.py
@@ -167,13 +172,18 @@ jobs:
   # ---------------------------------------------------------------------------
   # Clippy — enforces the deny-level lints in [workspace.lints] (root
   # Cargo.toml). `cargo clippy` exits nonzero only on `deny` lints, so
-  # warn-level output is informational and never blocks a PR. Separate from
-  # `lint` because it compiles the whole default-member set (~30 min cold);
-  # `lint` stays the fast fmt/gates job.
+  # warn-level output is informational and never blocks a PR. The product leg
+  # gives fast feedback for the CLI; the host-compatible leg names every Linux
+  # package explicitly. Neither scope depends on Cargo default-members.
   # ---------------------------------------------------------------------------
   clippy:
+    name: Clippy (${{ matrix.scope }})
     runs-on: ubuntu-latest
     timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        scope: [product, host-compatible]
     env:
       RUSTC_WRAPPER: sccache
       SCCACHE_GHA_ENABLED: "false"
@@ -206,8 +216,19 @@ jobs:
           shared-key: "${{ runner.os }}-perry"
           save-if: ${{ github.ref == 'refs/heads/main' }}
 
-      - name: Run clippy
-        run: cargo clippy
+      - name: Run clippy for explicit scope
+        run: |
+          if [[ "${{ matrix.scope }}" == "product" ]]; then
+            cargo clippy -p perry --bins
+          else
+            mapfile -t excluded < <(python3 scripts/workspace_architecture.py \
+              --print-excluded-scope host-compatible)
+            cargo_args=(--workspace)
+            for package in "${excluded[@]}"; do
+              cargo_args+=(--exclude "$package")
+            done
+            cargo clippy "${cargo_args[@]}"
+          fi
 
   # ---------------------------------------------------------------------------
   # API docs drift gate (#465)
@@ -306,9 +327,8 @@ jobs:
   # workaround). Each downstream job below builds in parallel directly.
   cargo-test:
     # Was macos-14 — moved to ubuntu-latest in v0.5.392 to drop the 10×
-    # billing weight. cargo-test's `--exclude` list already filters out
-    # every macOS-specific UI crate (perry-ui-{ios,visionos,tvos,
-    # watchos,gtk4,android,windows} per the comment block below), so
+    # billing weight. The centralized Linux test scope already filters out
+    # platform-specific UI crates, so
     # the platform-independent test set runs identically on Linux. The
     # macOS-host coverage we lose here is negligible — these tests
     # don't exercise any platform behavior; they're pure logic +
@@ -392,7 +412,8 @@ jobs:
           rm -rf target/perry-auto-* target/debug/libperry_ext_*.a 2>/dev/null || true
 
       - name: Run cargo test
-        # Exclude UI backends that don't build on the ubuntu-latest CI image:
+        # The exclusions below are maintained once in
+        # workspace-architecture.json and consumed by ci_test_scope.py:
         # - perry-ui-macos / perry-ui-ios / perry-ui-tvos / perry-ui-watchos
         #   / perry-ui-visionos: depend on `objc2` which only compiles on
         #   Apple platforms (`compile_error!` in objc2/src/lib.rs:219).

diff --git a/Cargo.toml b/Cargo.toml
@@ -43,6 +43,7 @@ members = [
     "crates/perry-ext-ws",
     "crates/perry-ext-net",
     "crates/perry-ext-http",
+    "crates/perry-ext-http-server",
     "crates/perry-ext-streams",
     "crates/perry-ext-fastify",
     "crates/perry-ext-pdf",
@@ -84,63 +85,6 @@ members = [
 # explicitly with -p on their target platform.
 default-members = [
     "crates/perry",
-    "crates/perry-parser",
-    "crates/perry-types",
-    "crates/perry-api-manifest",
-    "crates/perry-hir",
-    "crates/perry-transform",
-    "crates/perry-codegen",
-    "crates/perry-dispatch",
-    "crates/perry-runtime",
-    "crates/perry-ffi",
-    "crates/perry-ext-dotenv",
-    "crates/perry-ext-nanoid",
-    "crates/perry-ext-uuid",
-    "crates/perry-ext-slugify",
-    "crates/perry-ext-bcrypt",
-    "crates/perry-ext-argon2",
-    "crates/perry-ext-jsonwebtoken",
-    "crates/perry-ext-validator",
-    "crates/perry-ext-lru-cache",
-    "crates/perry-ext-better-sqlite3",
-    "crates/perry-ext-zlib",
-    "crates/perry-ext-exponential-backoff",
-    "crates/perry-ext-axios",
-    "crates/perry-ext-events",
-    "crates/perry-ext-decimal",
-    "crates/perry-ext-dayjs",
-    "crates/perry-ext-moment",
-    "crates/perry-ext-cheerio",
-    "crates/perry-ext-sharp",
-    "crates/perry-ext-ratelimit",
-    "crates/perry-ext-commander",
-    "crates/perry-ext-ethers",
-    "crates/perry-ext-nodemailer",
-    "crates/perry-ext-cron",
-    "crates/perry-ext-ioredis",
-    "crates/perry-ext-pg",
-    "crates/perry-ext-mysql2",
-    "crates/perry-ext-fetch",
-    "crates/perry-ext-mongodb",
-    "crates/perry-ext-ws",
-    "crates/perry-ext-net",
-    "crates/perry-ext-http",
-    "crates/perry-ext-streams",
-    "crates/perry-ext-fastify",
-    "crates/perry-ext-pdf",
-    "crates/perry-ext-ads",
-    "crates/perry-wasm-host",
-    "crates/perry-stdlib",
-    "crates/perry-diagnostics",
-    "crates/perry-ui",
-    "crates/perry-codegen-js",
-    "crates/perry-codegen-swiftui",
-    "crates/perry-codegen-arkts",
-    "crates/perry-codegen-glance",
-    "crates/perry-codegen-wear-tiles",
-    "crates/perry-codegen-wasm",
-    "crates/perry-updater",
-    "crates/perry-container-compose",
 ]
 
 # Aggressive release optimizations for small, fast binaries
@@ -505,6 +449,7 @@ perry-ext-mongodb = { path = "crates/perry-ext-mongodb" }
 perry-ext-ws = { path = "crates/perry-ext-ws" }
 perry-ext-net = { path = "crates/perry-ext-net" }
 perry-ext-http = { path = "crates/perry-ext-http" }
+perry-ext-http-server = { path = "crates/perry-ext-http-server" }
 perry-ext-streams = { path = "crates/perry-ext-streams" }
 perry-ext-fastify = { path = "crates/perry-ext-fastify" }
 perry-ext-pdf = { path = "crates/perry-ext-pdf" }

diff --git a/changelog.d/6758-workspace-architecture.md b/changelog.d/6758-workspace-architecture.md
@@ -0,0 +1 @@
+**Workspace architecture baseline:** make all 78 effective Cargo members explicit, reduce the default build to the Perry CLI and its 18-crate dependency closure, add a reproducible crate inventory and policy audit, and run Clippy against explicit product and host-compatible scopes.
diff --git a/crates/perry-ext-http/Cargo.toml b/crates/perry-ext-http/Cargo.toml
@@ -18,7 +18,7 @@ perry-ffi.workspace = true
 # `js_node_http2_*` symbols flow through into libperry_ext_http.a so a
 # single staticlib registration in well_known_bindings.toml covers
 # both client and server. The crate split keeps the source layered.
-perry-ext-http-server = { path = "../perry-ext-http-server" }
+perry-ext-http-server.workspace = true
 # #2154: Agent argument validation throws `RangeError [ERR_OUT_OF_RANGE]`
 # via `js_throw` + `register_error_code_pub`, which are perry-runtime's
 # Rust-ABI helpers (not perry-ffi's). Stays consistent with perry-stdlib's

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -174,4 +174,5 @@
 # Contributing
 
 - [Architecture](contributing/architecture.md)
+- [Crate policy](contributing/crate-policy.md)
 - [Building from Source](contributing/building.md)
diff --git a/docs/src/contributing/architecture.md b/docs/src/contributing/architecture.md
@@ -1,6 +1,7 @@
 # Architecture
 
-This is a brief overview for contributors. For detailed implementation notes, see the project's `CLAUDE.md`.
+This is a brief overview for contributors. The rules for creating, retaining,
+or removing workspace crates live in the [crate policy](crate-policy.md).
 
 ## Compilation Pipeline
 
@@ -24,19 +25,20 @@ Native Executable
 |-------|---------|
 | `perry` | CLI driver, command parsing, compilation orchestration |
 | `perry-parser` | SWC wrapper for TypeScript parsing |
-| `perry-types` | Type system definitions |
+| `perry-types` | Shared type definitions; tracked for consolidation into HIR |
 | `perry-hir` | HIR data structures (`ir.rs`) and AST→HIR lowering (`lower.rs`) |
 | `perry-transform` | IR passes: function inlining, closure conversion, async lowering |
-| `perry-codegen-llvm` | LLVM-based native code generation |
+| `perry-codegen` | LLVM-based native code generation |
 | `perry-codegen-wasm` | WebAssembly code generation for `--target web` / `--target wasm` (HIR → WASM bytecode + JS bridge) |
 | `perry-codegen-js` | Legacy JavaScript code generator (still present for the JS minifier; the JS-emit `--target web` path was consolidated into `perry-codegen-wasm`) |
 | `perry-codegen-swiftui` | SwiftUI code generation for WidgetKit extensions |
 | `perry-runtime` | Runtime library: NaN-boxed values, GC, arena allocator, objects, arrays, strings |
-| `perry-stdlib` | Node.js API implementations: mysql2, redis, fastify, bcrypt, etc. |
-| `perry-ui` | Shared UI types |
+| `perry-ffi` | Stable interface used by native binding crates |
+| `perry-stdlib` | Runtime-coupled Node.js and Perry standard-library implementations |
+| `perry-ext-*` | Independently linked native bindings selected per program |
+| `perry-ui` / `perry-ui-model` | Shared UI interface and public model metadata |
 | `perry-ui-macos` | macOS UI (AppKit) |
 | `perry-ui-ios` | iOS UI (UIKit) |
-| `perry-jsruntime` | JavaScript interop via QuickJS |
 
 ## Key Concepts
 
@@ -68,7 +70,7 @@ UI widgets are represented as small integer handles NaN-boxed with `POINTER_TAG`
 The codegen crate is organized into focused modules:
 
 ```
-perry-codegen-llvm/src/
+perry-codegen/src/
   codegen.rs       # Main entry, module compilation
   types.rs         # Type definitions, context structs
   util.rs          # Helper functions

diff --git a/docs/src/contributing/building.md b/docs/src/contributing/building.md
@@ -8,15 +8,20 @@
 ## Build
 
 ```bash
-git clone https://github.com/skelpo/perry.git
+git clone https://github.com/PerryTS/perry.git
 cd perry
 
-# Build all crates (release mode recommended)
+# Build the default product and its dependency closure
 cargo build --release
 ```
 
 The binary is at `target/release/perry`.
 
+The workspace deliberately defaults to the `perry` CLI. Bindings, platform
+adapters, test support, and release-only archives are selected explicitly by
+their CI/release jobs. Workspace-wide host commands must use the centralized
+platform exclusions described in the [crate policy](crate-policy.md).
+
 ## Build taxonomy (dev / release / dist)
 
 Perry has three build profiles, each tuned for a different job (#5422):
@@ -75,12 +80,15 @@ the full feature list (`full-cli`, `publish-cli`, `backend-wasm`, …).
 ## Run Tests
 
 ```bash
-# All tests (exclude iOS crate on non-iOS host)
-cargo test --workspace --exclude perry-ui-ios
+# Product unit targets
+cargo test -p perry --bins
+
+# Inspect the nightly CI test scope (all Linux-compatible test crates)
+python3 scripts/ci_test_scope.py --full </dev/null
 
 # Specific crate
 cargo test -p perry-hir
-cargo test -p perry-codegen-llvm
+cargo test -p perry-codegen
 ```
 
 ## Compile and Run TypeScript
@@ -97,8 +105,8 @@ cargo run --release -- hello.ts --print-hir
 ## Development Workflow
 
 1. Make changes to the relevant crate
-2. `cargo build --release` to build
-3. `cargo test --workspace --exclude perry-ui-ios` to verify
+2. `cargo check -p perry` for fast product feedback
+3. Run tests for the crates affected by the change
 4. Test with a real TypeScript file: `cargo run --release -- test.ts -o test && ./test`
 
 ## Project Structure
@@ -111,7 +119,7 @@ perry/
 │   ├── perry-types/        # Type definitions
 │   ├── perry-hir/          # HIR and lowering
 │   ├── perry-transform/    # IR passes
-│   ├── perry-codegen-llvm/ # LLVM native codegen
+│   ├── perry-codegen/      # LLVM native codegen
 │   ├── perry-codegen-wasm/ # WebAssembly codegen (--target web / --target wasm)
 │   ├── perry-codegen-js/   # JS minifier (formerly the web target's codegen)
 │   ├── perry-codegen-swiftui/ # Widget codegen
@@ -120,7 +128,7 @@ perry/
 │   ├── perry-ui/           # Shared UI types
 │   ├── perry-ui-macos/     # macOS AppKit UI
 │   ├── perry-ui-ios/       # iOS UIKit UI
-│   └── perry-jsruntime/    # QuickJS integration
+│   └── perry-ext-*/        # Selectively linked native bindings
 ├── docs/                   # This documentation (mdBook)
 ├── CLAUDE.md               # Detailed implementation notes
 └── CHANGELOG.md            # Version history
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Workspace architecture baseline: make all 78 effective Cargo members explicit, reduce the default build to the Perry CLI and its 18-crate dependency closure, add a reproducible crate inventory and policy audit, and run Clippy against explicit product and host-compatible scopes.