Merge pull request #122 from Tuntii/stabilize-facade-api

core: stabilize facade API surface, feature taxonomy, and public-api CI gate

Author: Tuntii

.gitattributes

@@ -1,2 +1,4 @@
 # Auto detect text files and perform LF normalization
 * text=auto
+api/public/*.txt text eol=lf
+.github/scripts/*.sh text eol=lf

.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"
+```

.github/PULL_REQUEST_TEMPLATE.md

@@ -24,6 +24,7 @@ Please include a summary of the changes and the related issue. Please also inclu
 - [ ] I have added tests that prove my fix is effective or that my feature works
 - [ ] New and existing unit tests pass locally with my changes
 - [ ] Any dependent changes have been merged and published in downstream modules
+- [ ] If `api/public/*` snapshots changed, this PR has `breaking` or `feature` label
 
 ## Related Issues
 
@@ -44,4 +45,4 @@ Add screenshots to help explain your changes.
 
 ## Additional Notes
 
-Add any other context about the pull request here.
+Add any other context about the pull request here.

.github/scripts/public_api_label_gate.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+base_sha="${BASE_SHA:?BASE_SHA is required}"
+head_sha="${HEAD_SHA:?HEAD_SHA is required}"
+
+changed_snapshots="$(
+  git diff --name-only "$base_sha" "$head_sha" -- \
+    api/public/rustapi-rs.default.txt \
+    api/public/rustapi-rs.all-features.txt
+)"
+
+if [[ -z "$changed_snapshots" ]]; then
+  echo "No public API snapshot changes detected."
+  exit 0
+fi
+
+# Collect labels from env first, then fall back to GitHub event payload.
+labels_csv="${PR_LABELS:-}"
+if [[ -z "$labels_csv" && -n "${GITHUB_EVENT_PATH:-}" && -f "${GITHUB_EVENT_PATH}" ]]; then
+  if command -v jq >/dev/null 2>&1; then
+    labels_csv="$(jq -r '.pull_request.labels[].name' "$GITHUB_EVENT_PATH" 2>/dev/null | paste -sd ',' -)"
+  fi
+fi
+
+labels_normalized=",$(echo "$labels_csv" | tr '[:upper:]' '[:lower:]'),"
+echo "Detected PR labels: ${labels_csv:-<none>}"
+
+if [[ "$labels_normalized" == *",breaking,"* || "$labels_normalized" == *",feature,"* ]]; then
+  echo "Public API snapshots changed and required label is present."
+  exit 0
+fi
+
+echo "::error::Public API snapshots changed but PR is missing required label: breaking or feature."
+echo "Changed snapshot files:"
+echo "$changed_snapshots"
+exit 1

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

@@ -0,0 +1,67 @@
+# RustAPI Contract
+
+This document defines compatibility guarantees for the RustAPI workspace.
+
+## 1. Scope
+
+- Stable public contract:
+  - `rustapi-rs` (facade crate)
+  - `cargo-rustapi` (CLI surface)
+- Internal implementation crates (best-effort, no stability guarantee):
+  - `rustapi-core`, `rustapi-openapi`, `rustapi-validate`, `rustapi-macros`
+  - `rustapi-extras`, `rustapi-ws`, `rustapi-toon`, `rustapi-view`, `rustapi-grpc`
+  - `rustapi-testing`, `rustapi-jobs`
+
+Do not depend on internal crate APIs for long-term compatibility.
+
+## 2. SemVer Policy
+
+- `rustapi-rs` follows strict SemVer:
+  - Breaking changes: major
+  - Additive changes: minor
+  - Fixes/internal-only changes: patch
+- Public API surface is tracked by committed snapshots:
+  - `api/public/rustapi-rs.default.txt`
+  - `api/public/rustapi-rs.all-features.txt`
+- Pull requests that change snapshots must be labeled:
+  - `breaking` (if compatibility breaks)
+  - `feature` (if additive API surface change)
+
+## 3. MSRV Policy
+
+- Workspace MSRV is pinned to Rust `1.78`.
+- MSRV increases are allowed only in minor or major releases.
+- MSRV changes must be called out in changelog/release notes.
+- Patch releases must not raise MSRV.
+
+## 4. Deprecation Policy
+
+- Deprecations are soft-first:
+  - `#[deprecated]` attribute
+  - 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
+
+- New facade feature names must follow taxonomy:
+  - `core-*`
+  - `protocol-*`
+  - `extras-*`
+- Meta features:
+  - `core` (default)
+  - `protocol-all`
+  - `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
+
+- Public facade signatures should not expose internal crate paths.
+- Macro/runtime internals are allowed only via `rustapi_rs::__private` and are excluded from stability guarantees.

README.md

@@ -114,6 +114,22 @@ async fn list_users() -> &'static str { "ok" }
 *   ✅ **Multi-threaded Runtime**
 *   ✅ **Zero Config**
 
+## Feature Taxonomy (Stable)
+
+RustAPI now groups features into three namespaces:
+
+| Namespace | Purpose | Examples |
+|:--|:--|:--|
+| `core-*` | Core framework capabilities | `core-openapi`, `core-tracing`, `core-http3` |
+| `protocol-*` | Optional protocol crates | `protocol-toon`, `protocol-ws`, `protocol-view`, `protocol-grpc` |
+| `extras-*` | Optional production middleware/integrations | `extras-jwt`, `extras-cors`, `extras-rate-limit`, `extras-replay` |
+
+Meta features:
+- `core` (default)
+- `protocol-all`
+- `extras-all`
+- `full = core + protocol-all + extras-all`
+
 ## ✨ Latest Release Highlights (v0.1.335)
 
 *   ✅ **Dual-Stack Runtime**: Simultaneous HTTP/1.1 (TCP) and HTTP/3 (QUIC/UDP) support