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

[Tuntii]

Introduce a canonical feature taxonomy (core-, protocol-, extras-) and migrate legacy feature aliases for compatibility. Refactor the rustapi-rs facade to expose stable namespaces (core, protocol, extras) and provide backward-compatible root aliases; update Cargo.toml features accordingly. Add CONTRACT.md to document the public contract and SemVer/MSRV/deprecation policies. Add committed public API snapshots (api/public/) and a GitHub Actions workflow plus script to detect snapshot drift and require a breaking or feature PR label. Update templates, CLI, tests, and docs to use the new feature names. Make several internal API adjustments: seal the Handler trait, adjust module visibility/exports in rustapi-core, and update procedural macros to resolve internal crate paths via the facade's __private exports. Remove RELEASES.md and apply related README/architecture documentation tweaks.

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test addition or update
• CI/CD changes
• Other (please describe):

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• 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

Testing

Please describe the tests that you ran to verify your changes:

• Unit tests
• Integration tests
• Manual testing
• Other (please describe):

Additional Notes

This pull request introduces a new public API compatibility contract for the RustAPI workspace, enforces stricter SemVer and feature flag taxonomy, and implements automated CI checks to ensure any changes to the public API are properly labeled as breaking or feature additions. It also updates the CLI, templates, and documentation to align with the new feature taxonomy, and improves macro hygiene for internal path resolution. Below are the most important changes:

Public API Compatibility & CI Enforcement

• Added CONTRACT.md to define the public API compatibility contract, SemVer policy, MSRV, deprecation rules, feature flag taxonomy, and internal leakage rules for the RustAPI workspace.
• Introduced a GitHub Actions workflow (.github/workflows/public-api.yml) and a shell script (.github/scripts/public_api_label_gate.sh) to check for changes in public API snapshot files and enforce that such PRs are labeled as breaking or feature. [1] [2]
• Updated the pull request template to remind contributors to add the appropriate label if public API snapshots change.

Feature Flag Taxonomy & CLI Alignment

• Updated CLI feature selection and project templates to use the new extras-* and protocol-* feature naming conventions instead of legacy names like jwt, cors, or ws. This affects both the CLI logic and generated Cargo.toml/config comments. [1] [2] [3] [4] [5] [6] [7] [8]
• Added a new "Feature Taxonomy" section to the README.md explaining the new namespaces (core-*, protocol-*, extras-*) and meta features.

Macro & Internal Path Hygiene

• Improved macro hygiene in crates/rustapi-macros by dynamically resolving paths to internal crates (e.g., rustapi-core, rustapi-openapi) to avoid leaking internal paths in public APIs and to support both direct and re-exported usage. [1] [2] [3] [4] [5]

Internal API Visibility & Cleanups

• Made several modules in rustapi-core (auto_route, auto_schema, json, path_params, path_validation) private or crate-private to prevent accidental public exposure of internal APIs. [1] [2]
• Re-exported PathParams from the crate root for public consumption.
• Added a sealed trait to the Handler trait in rustapi-core to prevent external implementations, further locking down the public API.

Documentation & Release Notes

• Removed outdated release notes from RELEASES.md in favor of the new contract and taxonomy documentation.

These changes collectively ensure that the public API surface is well-defined, changes are properly tracked and reviewed, and the feature flag system is consistent and future-proof.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.