Add branch-protection doc; update API, code & docs

Add .github/BRANCH_PROTECTION.md with UI and API instructions for protecting main and requiring Public API checks. Update CHANGELOG and CONTRACT to document facade-first CORE stabilization, public API governance (snapshots/CI), feature taxonomy and deprecation/migration timeline. Silence unused-symbol warnings by adding #[allow(dead_code)] to several rustapi-core helpers and path validation types/functions, and conditionally gate sqlx-related imports in rustapi-extras with feature cfgs. Refresh docs and examples to the new feature naming scheme (extras-*, protocol-*, core-*) and update performance wording to reflect the renamed simd-json feature.

Author: Tuntii

.github/BRANCH_PROTECTION.md

@@ -0,0 +1,54 @@
+# Branch Protection Setup
+
+Configure branch protection for `main` so public API checks are required.
+
+## Required Status Checks
+
+Add these checks as required:
+
+- `Public API / Snapshot Drift`
+- `Public API / Label Gate`
+
+## GitHub UI Path
+
+1. Repository `Settings`
+2. `Branches`
+3. Edit rule for `main`
+4. Enable `Require status checks to pass before merging`
+5. Add the two checks above
+
+## API Automation (optional)
+
+Use a fine-grained token with `Administration: Read and write` for the repository.
+
+```powershell
+$owner = "Tuntii"
+$repo = "RustAPI"
+$token = $env:GITHUB_TOKEN
+
+$body = @{
+  required_status_checks = @{
+    strict = $true
+    contexts = @(
+      "Public API / Snapshot Drift",
+      "Public API / Label Gate"
+    )
+  }
+  enforce_admins = $true
+  required_pull_request_reviews = @{
+    required_approving_review_count = 1
+  }
+  restrictions = $null
+} | ConvertTo-Json -Depth 10
+
+Invoke-RestMethod `
+  -Method Put `
+  -Uri "https://api.github.com/repos/$owner/$repo/branches/main/protection" `
+  -Headers @{
+    Authorization = "Bearer $token"
+    Accept = "application/vnd.github+json"
+    "X-GitHub-Api-Version" = "2022-11-28"
+  } `
+  -Body $body `
+  -ContentType "application/json"
+```

CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- **Facade-first CORE stabilization**:
+  - `rustapi-rs` public surface is now explicitly curated (`core`, `protocol`, `extras`, `prelude`).
+  - Internal wiring moved behind `rustapi_rs::__private` for macro/runtime integration.
+  - `rustapi-core` internal modules tightened (`pub(crate)`/private where applicable).
+  - `Handler` trait sealed to prevent external implementation leakage.
+- **Feature taxonomy refresh**:
+  - Canonical naming is now `core-*`, `protocol-*`, `extras-*`.
+  - Meta features standardized: `core`, `protocol-all`, `extras-all`, `full`.
+  - Legacy feature names remain as compatibility aliases and are deprecated.
+
+### Added
+- **Public API governance**:
+  - Snapshot files under `api/public/` for `rustapi-rs` (default + all-features).
+  - New CI workflow `.github/workflows/public-api.yml`:
+    - snapshot drift check
+    - PR label gate requiring `breaking` or `feature` when snapshot changes.
+- **Compatibility contract**:
+  - New `CONTRACT.md` defining SemVer, MSRV (1.78), deprecation and feature policies.
+
+### Deprecated
+- Legacy facade paths and feature aliases are soft-deprecated and scheduled for removal no earlier than two minor releases after announcement.
+
 ## [0.1.300] - 2026-02-06
 
 ### Added

CONTRACT.md

@@ -41,6 +41,8 @@ Do not depend on internal crate APIs for long-term compatibility.
   - explicit migration path in docs/release notes
 - Minimum deprecation window before removal: 2 minor releases.
 - Removals occur only in major releases.
+- Current compatibility window for legacy aliases introduced in this cycle:
+  - First eligible removal: `v0.3.0` (assuming deprecation introduced in `v0.1.x`).
 
 ## 5. Feature Flag Policy
 
@@ -54,6 +56,10 @@ Do not depend on internal crate APIs for long-term compatibility.
   - `extras-all`
   - `full`
 - Legacy aliases may exist temporarily for migration but must be treated as deprecated and eventually removed on a published timeline.
+- Published timeline for this migration set:
+  - `v0.1.x`: aliases available, deprecation warnings/documentation.
+  - `v0.2.x`: aliases still available, migration reminders.
+  - `v0.3.0+`: aliases may be removed.
 
 ## 6. Internal Leakage Rule
 

crates/rustapi-core/src/auto_route.rs

@@ -67,6 +67,7 @@ pub fn collect_auto_routes() -> Vec<Route> {
 /// Get the count of auto-registered routes without collecting them.
 ///
 /// Useful for debugging and logging.
+#[allow(dead_code)]
 pub fn auto_route_count() -> usize {
     AUTO_ROUTES.len()
 }

crates/rustapi-core/src/auto_schema.rs

@@ -21,6 +21,7 @@ pub fn apply_auto_schemas(spec: &mut rustapi_openapi::OpenApiSpec) {
 }
 
 /// Get the count of auto-registered schema registration functions.
+#[allow(dead_code)]
 pub fn auto_schema_count() -> usize {
     AUTO_SCHEMAS.len()
 }

crates/rustapi-core/src/json.rs

@@ -49,6 +49,7 @@ pub fn from_slice<T: DeserializeOwned>(slice: &[u8]) -> Result<T, JsonError> {
 /// This variant allows simd-json to parse in-place without copying,
 /// providing maximum performance.
 #[cfg(feature = "simd-json")]
+#[allow(dead_code)]
 pub fn from_slice_mut<T: DeserializeOwned>(slice: &mut [u8]) -> Result<T, JsonError> {
     simd_json::from_slice(slice).map_err(JsonError::SimdJson)
 }
@@ -57,6 +58,7 @@ pub fn from_slice_mut<T: DeserializeOwned>(slice: &mut [u8]) -> Result<T, JsonEr
 ///
 /// Falls back to standard implementation when simd-json is disabled.
 #[cfg(not(feature = "simd-json"))]
+#[allow(dead_code)]
 pub fn from_slice_mut<T: DeserializeOwned>(slice: &mut [u8]) -> Result<T, JsonError> {
     serde_json::from_slice(slice).map_err(JsonError::SerdeJson)
 }
@@ -65,6 +67,7 @@ pub fn from_slice_mut<T: DeserializeOwned>(slice: &mut [u8]) -> Result<T, JsonEr
 ///
 /// Uses pre-allocated buffer with estimated capacity for better performance.
 #[cfg(feature = "simd-json")]
+#[allow(dead_code)]
 pub fn to_vec<T: Serialize>(value: &T) -> Result<Vec<u8>, JsonError> {
     simd_json::to_vec(value).map_err(JsonError::SimdJson)
 }
@@ -73,6 +76,7 @@ pub fn to_vec<T: Serialize>(value: &T) -> Result<Vec<u8>, JsonError> {
 ///
 /// Uses pre-allocated buffer with estimated capacity for better performance.
 #[cfg(not(feature = "simd-json"))]
+#[allow(dead_code)]
 pub fn to_vec<T: Serialize>(value: &T) -> Result<Vec<u8>, JsonError> {
     serde_json::to_vec(value).map_err(JsonError::SerdeJson)
 }
@@ -106,6 +110,7 @@ pub fn to_vec_with_capacity<T: Serialize>(
 }
 
 /// Serialize a value to a pretty-printed JSON byte vector.
+#[allow(dead_code)]
 pub fn to_vec_pretty<T: Serialize>(value: &T) -> Result<Vec<u8>, JsonError> {
     serde_json::to_vec_pretty(value).map_err(JsonError::SerdeJson)
 }

crates/rustapi-core/src/path_validation.rs

@@ -6,6 +6,7 @@
 
 /// Result of path validation
 #[derive(Debug, Clone, PartialEq, Eq)]
+#[allow(dead_code)]
 pub enum PathValidationError {
     /// Path must start with '/'
     MustStartWithSlash { path: String },
@@ -151,6 +152,7 @@ impl std::error::Error for PathValidationError {}
 /// assert!(validate_path("/users/{}").is_err()); // Empty parameter
 /// assert!(validate_path("/users/{123}").is_err()); // Parameter starts with digit
 /// ```
+#[allow(dead_code)]
 pub fn validate_path(path: &str) -> Result<(), PathValidationError> {
     // Path must start with /
     if !path.starts_with('/') {
@@ -250,6 +252,7 @@ pub fn validate_path(path: &str) -> Result<(), PathValidationError> {
 }
 
 /// Check if a path is valid (convenience function)
+#[allow(dead_code)]
 pub fn is_valid_path(path: &str) -> bool {
     validate_path(path).is_ok()
 }

crates/rustapi-extras/src/sqlx/mod.rs

@@ -48,8 +48,18 @@
 //! }
 //! ```
 
+#[cfg(any(
+    feature = "sqlx-postgres",
+    feature = "sqlx-mysql",
+    feature = "sqlx-sqlite"
+))]
 use rustapi_core::health::{HealthCheck, HealthCheckBuilder, HealthStatus};
 use rustapi_core::ApiError;
+#[cfg(any(
+    feature = "sqlx-postgres",
+    feature = "sqlx-mysql",
+    feature = "sqlx-sqlite"
+))]
 use std::sync::Arc;
 use std::time::Duration;
 use thiserror::Error;

docs/PHILOSOPHY.md

@@ -117,16 +117,16 @@ rustapi-rs = "0.1.335"
 rustapi-rs = { version = "0.1.335", features = ["full"] }
 
 # Pick what you need
-rustapi-rs = { version = "0.1.335", features = ["jwt", "cors", "toon"] }
+rustapi-rs = { version = "0.1.335", features = ["extras-jwt", "extras-cors", "protocol-toon"] }
 ```
 
 | Feature | What You Get |
 |---------|--------------|
-| `jwt` | JWT authentication with `AuthUser<T>` extractor |
-| `cors` | CORS middleware with builder pattern |
-| `rate-limit` | IP-based rate limiting |
-| `toon` | LLM-optimized TOON format |
-| `swagger-ui` | Auto-generated `/docs` endpoint |
+| `extras-jwt` | JWT authentication with `AuthUser<T>` extractor |
+| `extras-cors` | CORS middleware with builder pattern |
+| `extras-rate-limit` | IP-based rate limiting |
+| `protocol-toon` | LLM-optimized TOON format |
+| `core-openapi` | Auto-generated `/docs` endpoint |
 | `full` | All features enabled |
 
 ### 5. 🤖 LLM-First Design
@@ -219,7 +219,7 @@ async fn handler(Json(body): Json<T>) -> Json<R>
 
 ### Short Term (v0.x)
 - Polish existing features
-- Performance optimizations (simd-json, better allocations)
+- Performance optimizations (`core-simd-json`, better allocations)
 - More middleware (compression, static files)
 
 ### Medium Term (v1.0)

docs/cookbook/src/concepts/performance.md

@@ -80,7 +80,7 @@ Performance is not a guessing game. Below are results from our internal benchmar
 | Framework | Requests/sec | Latency (avg) | Memory |
 |-----------|--------------|---------------|--------|
 | **RustAPI** | **~185,000** | **~0.54ms** | **~8MB** |
-| **RustAPI + simd-json** | **~220,000** | **~0.45ms** | **~8MB** |
+| **RustAPI + core-simd-json** | **~220,000** | **~0.45ms** | **~8MB** |
 | Actix-web | ~178,000 | ~0.56ms | ~10MB |
 | Axum | ~165,000 | ~0.61ms | ~12MB |
 | Rocket | ~95,000 | ~1.05ms | ~15MB |
@@ -105,7 +105,7 @@ cd benches
 
 | Optimization | Description |
 |--------------|-------------|
-| ⚡ **SIMD-JSON** | 2-4x faster JSON parsing with `simd-json` feature |
+| ⚡ **SIMD-JSON** | 2-4x faster JSON parsing with `core-simd-json` feature |
 | 🔄 **Zero-copy parsing** | Direct memory access for path/query params |
 | 📦 **SmallVec PathParams** | Stack-optimized path parameters |
 | 🎯 **Compile-time dispatch** | All extractors resolved at compile time |