<!--
SYNC IMPACT REPORT
==================
Version change: 0.0.0 (template) → 1.0.0 (initial ratification)
Modified principles: N/A (initial creation)
Added sections:
  - Core Principles (7 principles)
  - Platform Requirements
  - Quality Gates
  - Governance
Removed sections: N/A
Templates requiring updates:
  ✅ .specify/templates/plan-template.md (Constitution Check section compatible)
  ✅ .specify/templates/spec-template.md (Requirements section compatible)
  ✅ .specify/templates/tasks-template.md (Test-first workflow compatible)
Follow-up TODOs: None
-->

# LastID Rust SDK Constitution

## Core Principles

### I. Customer-Facing Quality (NON-NEGOTIABLE)

This SDK is a public, open source library consumed by external developers. Every API surface, error message, and documentation artifact MUST meet production-grade quality standards.

- All public APIs MUST have comprehensive rustdoc with examples
- Error messages MUST be actionable and user-friendly
- Breaking changes MUST follow semantic versioning with migration guides
- Public types MUST derive common traits (Debug, Clone, PartialEq) where applicable

### II. Test Coverage (NON-NEGOTIABLE)

All code MUST maintain **95% minimum test coverage** measured by line and branch coverage.

- Coverage reports MUST be generated on every PR via `cargo llvm-cov`
- PRs that drop coverage below 95% MUST NOT be merged
- Tests MUST cover happy paths, error paths, and edge cases
- Property-based testing via `proptest` MUST be used for parsers and serializers
- WASM target MUST have dedicated `wasm-bindgen-test` coverage

### III. Code Cleanliness (NON-NEGOTIABLE)

All code MUST pass `clippy::pedantic` with zero warnings and maintain strict lint standards.

- `#![forbid(unsafe_code)]` MUST remain enforced at crate level
- All clippy lint groups (`all`, `pedantic`, `nursery`, `cargo`) MUST pass
- Explicit `#[allow(...)]` annotations require justification comments
- `cargo fmt` MUST pass with no changes required
- No `TODO` or `FIXME` comments in merged code without linked issue

### IV. Cross-Platform Compatibility (NON-NEGOTIABLE)

This SDK targets all major platforms: Web (WASM), iOS, Android, Windows, macOS, Linux.

- All features MUST compile for `wasm32-unknown-unknown` target
- Platform-specific code MUST use conditional compilation (`#[cfg(...)]`)
- No platform-specific dependencies without corresponding feature flags
- CI MUST verify compilation for all supported targets:
  - `x86_64-unknown-linux-gnu`
  - `x86_64-apple-darwin` / `aarch64-apple-darwin`
  - `x86_64-pc-windows-msvc`
  - `wasm32-unknown-unknown`
  - `aarch64-linux-android` / `aarch64-apple-ios`

### V. Safe Updates (NON-NEGOTIABLE)

Modifications MUST prioritize in-place updates over rewrites, with safety verification.

- Prefer `Edit` over `Write` for existing files
- Changes MUST preserve existing public API contracts unless explicitly versioning a breaking change
- Refactors MUST maintain test coverage and pass all existing tests
- Dependency updates MUST be verified against all platform targets
- Security advisories (RUSTSEC) MUST be addressed within 48 hours of disclosure

### VI. Maintainability

Code MUST be written for long-term maintenance by the community.

- Functions MUST be under 50 lines; modules under 500 lines
- Complex logic MUST have inline comments explaining "why" not "what"
- Type-state patterns MUST be used for compile-time API correctness
- Generic code MUST have trait bounds documented
- Error types MUST implement `std::error::Error` and provide context

### VII. Security-First

All cryptographic and identity operations MUST follow security best practices.

- Secrets MUST use `secrecy::SecretString` or `zeroize` on drop
- No logging of credentials, tokens, or PII
- DPoP keys MUST be ephemeral or hardware-backed where available
- All HTTP MUST use TLS (rustls for native, browser-provided for WASM)
- Input validation MUST occur at API boundaries

## Platform Requirements

| Platform | Target Triple | HTTP Stack | Crypto | Cache |
|----------|--------------|------------|--------|-------|
| Linux | `x86_64-unknown-linux-gnu` | reqwest + rustls | p256 | mini-moka |
| macOS | `x86_64/aarch64-apple-darwin` | reqwest + rustls | p256 | mini-moka |
| Windows | `x86_64-pc-windows-msvc` | reqwest + rustls | p256 | mini-moka |
| iOS | `aarch64-apple-ios` | reqwest + rustls | p256 | mini-moka |
| Android | `aarch64-linux-android` | reqwest + rustls | p256 | mini-moka |
| Web/WASM | `wasm32-unknown-unknown` | reqwest + fetch | p256 | micro-moka |

- Feature flags MUST enable platform-appropriate dependencies
- Native platforms use tokio runtime; WASM uses wasm-bindgen-futures
- Storage abstraction MUST work across all platforms (TOML config, env vars)

## Quality Gates

Every PR MUST pass these automated checks before merge:

1. **Compilation**: `cargo build --workspace --all-features` (all targets)
2. **Tests**: `cargo test --workspace --all-features` (95%+ coverage)
3. **WASM Tests**: `wasm-pack test --headless`
4. **Lints**: `cargo clippy --workspace --all-features -- -D warnings`
5. **Format**: `cargo fmt --check`
6. **Docs**: `cargo doc --no-deps --all-features` (no warnings)
7. **Security**: `cargo audit` (no advisories above informational)
8. **MSRV**: Compile with declared `rust-version` in Cargo.toml

Manual review MUST verify:
- Public API changes have documentation updates
- Breaking changes have migration guide in CHANGELOG
- New dependencies are justified and license-compatible (MIT/Apache-2.0)

## Governance

This constitution supersedes all other development practices for the LastID Rust SDK.

**Amendment Process**:
1. Propose change via PR to this file with rationale
2. Require approval from at least 2 maintainers
3. Document migration plan if principles change
4. Update version following semver (MAJOR for principle removal/redefinition, MINOR for additions, PATCH for clarifications)

**Compliance Verification**:
- All PRs MUST reference constitution principles in review checklist
- CI MUST enforce Quality Gates automatically
- Quarterly audits MUST verify constitution adherence

**Guidance Files**:
- Runtime development guidance: `CLAUDE.md` (parent repo) and `README.md`
- Feature specifications: `.specify/` directory
- API documentation: `docs.rs/lastid-sdk`

**Version**: 1.0.0 | **Ratified**: 2026-01-17 | **Last Amended**: 2026-01-17
