syntaxis/DEPENDENCIES.md

# Canonical Dependency Registry - syntaxis

**Last Updated**: 2025-11-15
**Managed By**: dependency-manager tool
**Location**: Root `DEPENDENCIES.md` (with symlink from `.claude/DEPENDENCIES.md`)

---

## Overview

This document defines the canonical dependency registry for all crates in syntaxis. All crate dependencies must use versions and features defined here. This ensures:

- **Single source of truth**: No version conflicts across monorepo
- **Reproducible builds**: Consistent dependency resolution
- **Security**: Centralized vulnerability management
- **Compatibility**: Proven feature combinations

---

## Tier 1: Critical Dependencies (Must Maintain Consistency)

Dependencies that affect runtime behavior, async execution, or critical system functionality.

### Runtime & Async

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **tokio** | `1.48` | `["full"]` | Stable async runtime; pinned for reproducibility |
| **futures** | `0.3` | (none) | Async utilities and trait implementations |

### Serialization

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **serde** | `1.0` | `["derive"]` | Universal serialization framework |
| **serde_json** | `1.0` | (none) | JSON serialization |
| **toml** | `0.9` | (none) | TOML configuration parsing |
| **uuid** | `1.18` | `["v4", "serde"]` | Unique ID generation with serialization |

### Error Handling

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **thiserror** | `2.0` | (none) | **BREAKING from 1.0** - Standard error handling |
| **anyhow** | `1.0` | (none) | Flexible error context and propagation |

### Web Framework Stack

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **axum** | `0.8` | `["ws"]` | Web framework with WebSocket support |
| **tower** | `0.5` | (none) | HTTP middleware and service traits |
| **tower-http** | `0.6` | `["trace", "cors", "fs"]` | HTTP utilities (tracing, CORS, file serving) |
| **tokio-rustls** | `0.26` | (none) | TLS support for async |
| **rustls** | `0.23` | (none) | Modern TLS library (not OpenSSL) |
| **rustls-pemfile** | `2.2` | (none) | PEM certificate/key parsing |

### HTTP Client

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **reqwest** | `0.12` | `["json"]` | Async HTTP client with JSON support |

### Database

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **sqlx** | `0.8` | `["runtime-tokio-native-tls", "sqlite", "macros"]` | Async SQL with SQLite backend |
| **sqlx-sqlite** | `0.8` | (none) | SQLite-specific sqlx features |
| **surrealdb** | `2.3` | `["kv-mem", "kv-rocksdb"]` | Modern multi-backend database with embedded/server modes |
| **serde_bytes** | `0.11` | (none) | Binary data serialization for database fields |

### Authentication

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **jsonwebtoken** | `10.2` | `["aws_lc_rs"]` | **IMPORTANT: Use aws_lc_rs NOT rust_crypto** - JWT tokens |

---

## Tier 2: Important Dependencies (Frequently Used)

Dependencies that provide core functionality but with less critical version coupling.

### CLI Framework

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **clap** | `4.5` | `["derive"]` | CLI argument parsing with procedural macros |
| **clap_complete** | `4.5` | (none) | Shell completion generation |
| **colored** | `3.0` | (none) | Terminal color support |
| **prettytable-rs** | `0.10` | (none) | Formatted table output |
| **inquire** | `0.9` | (none) | Interactive CLI prompts |
| **console** | `0.15` | (none) | Console/terminal utilities |

### Terminal UI (TUI)

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **ratatui** | `0.30.0-beta.0` | `["all-widgets"]` | **BETA** - TUI widgets (latest + experimental) |
| **crossterm** | `0.29` | `["serde"]` | Terminal backend for ratatui |
| **palette** | `0.7` | `["serializing"]` | Color utilities with serialization |

### Web Frontend (Leptos/WASM)

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **leptos** | `0.8.12` | `["csr"]` | WASM frontend framework (client-side rendering) |
| **leptos_router** | `0.8.9` | (none) | Routing for Leptos applications |
| **leptos_meta** | `0.8.5` | (none) | Meta tag management for Leptos |
| **wasm-bindgen** | `0.2` | (none) | WASM JavaScript bindings |
| **gloo-net** | `0.6` | (none) | HTTP client for WASM |
| **web-sys** | `0.3` | (none) | Web APIs for WASM |
| **wasm-logger** | `0.2` | (none) | Logging for WASM applications |

### Utilities & Helpers

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **chrono** | `0.4` | `["serde"]` | Date/time handling with serialization |
| **camino** | `1.2` | (none) | UTF-8 paths (safer than std::path) |
| **walkdir** | `2.5` | (none) | Recursive directory iteration |
| **handlebars** | `6.3` | (none) | Template engine |
| **indexmap** | `2.12` | (none) | Ordered maps/sets |
| **regex** | `1.12` | (none) | Regular expressions |
| **once_cell** | `1.21` | (none) | Lazy static initialization |
| **dirs** | `6.0` | (none) | Platform-specific directories |

### Logging & Tracing

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **tracing** | `0.1` | (none) | Structured logging/tracing |
| **tracing-subscriber** | `0.3` | `["env-filter"]` | Logging subscriber with filtering |

### Metrics & Monitoring

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **prometheus** | `0.14` | `["process"]` | Prometheus metrics collection |

### Caching

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **moka** | `0.12` | `["future"]` | High-performance async cache |

### WebSocket

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **tokio-tungstenite** | `0.28` | (none) | WebSocket support for tokio |

### Messaging

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **async-nats** | `0.45` | (none) | NATS messaging client |

---

## Tier 3: Stable Dependencies (Dev/Test Only)

Dependencies used exclusively in testing, benchmarking, or development.

| Dependency | Version | Features | Rationale |
|-----------|---------|----------|-----------|
| **tokio-test** | `0.4` | (none) | Tokio async testing utilities |
| **tempfile** | `3.23` | (none) | Temporary files for testing |
| **assert_cmd** | `2.1` | (none) | CLI command assertion testing |
| **predicates** | `3.1` | (none) | Predicate assertions |
| **criterion** | `0.7` | `["html_reports"]` | Benchmarking framework |
| **mockito** | `1.6` | (none) | HTTP mocking for tests |

---

## Breaking Changes & Migration Notes

### ⚠️ SurrealDB 2.3 Upgrade (Recently Applied)

**What Changed**: Major API changes in SurrealDB 2.3 from 1.5

**Key Differences**:
- Parameter binding: `.bind(json!({ "key": value }))` instead of `.bind(("key", value))`
- Query patterns: Parameterized SQL with `$placeholders`
- Builder API: Removed in favor of explicit query methods
- Features: `kv-mem` for in-memory and `kv-rocksdb` for embedded persistence

**Migration Status**: ✅ Complete - syntaxis-core and syntaxis-cli fully migrated

**See Also**: `SURREALDB_2_3_MIGRATION.md` for detailed migration guide

---

### ⚠️ thiserror 2.0 Upgrade (Already Applied)

**What Changed**: API changes from 1.0 to 2.0

**Migration Required**: All error types using `#[error(...)]` macro updated

**Status in syntaxis**: ✅ Complete - all crates use 2.0

---

### ⚠️ jsonwebtoken Features Selection (CRITICAL)

**Always Use**: `features = ["aws_lc_rs"]`
**Never Use**: `features = ["rust_crypto", "use_pem"]`

**Rationale**:
- `aws_lc_rs`: AWS-backed cryptography, better performance, modern
- `rust_crypto`: Legacy pure-Rust implementation, slower
- Feature conflict causes compilation failures

**Current Status**:
- ❌ Root workspace: Still has 9.3 (will be updated to 10.2)
- ✅ syntaxis: Uses 10.2 with `aws_lc_rs`

---

### ⚠️ ratatui Beta Version (0.30.0-beta.0)

**Status**: Using bleeding-edge beta

**Why**: Latest widget support and features required for TUI

**Stability**: Production-ready for syntaxis TUI (heavily tested)

**Migration Path**: Switch to stable 0.30.0 when released (no breaking changes expected)

---

## Workspace Structure

### Root Workspace (`Cargo.toml`)

Defines all canonical versions in `[workspace.dependencies]`:

```toml
[workspace]
members = [
    "shared/rust-api/shared-api-lib",
    "shared/rust-tui",
    "shared/rust",
    "core/crates/syntaxis-core",
    # ... 10 members total
]

exclude = [
    "core/crates/syntaxis-api",      # WIP (37 errors)
    "core/crates/syntaxis-vapora",   # Planned
]

[workspace.dependencies]
# All 50+ dependencies defined here
```

### Nested Workspaces

- ❌ `syntaxis/Cargo.toml` should **NOT** have `[workspace]` section
- The root workspace already declares all crates as members
- Nested workspace definition causes anti-pattern warnings

### Shared Libraries

**Location**: `shared/rust/`, `shared/rust-api/shared-api-lib/`, `shared/rust-tui/`

**Strategy**: Portable but aligned
- Each lib maintains its own `Cargo.toml` for independence
- dependency-manager tool validates versions match canonical registry
- No workspace inheritance needed (libs can be used outside monorepo)

---

## Version Selection Rationale

### Tokio: Why 1.48 (not flexible "1")?

- **Stability**: Thoroughly tested production release
- **Compatibility**: All async crates tested against this version
- **Reproducibility**: Pinning prevents unexpected upgrades
- **Performance**: 1.48 has optimizations over 1.40-1.47

### Jsonwebtoken: Why 10.2 with aws_lc_rs?

- **Modern cryptography**: AWS-backed implementation (industry standard)
- **Performance**: 2-3x faster than pure-Rust crypto
- **Security**: Regular audits by AWS
- **Interoperability**: Works with standard JWT libraries

### Axum: Why 0.8 (not 0.9)?

- **Stability**: Mature, battle-tested version
- **Compatibility**: Perfect alignment with tokio 1.48
- **Router API**: Stable and well-documented
- **Upgrade path**: 0.9 can be adopted later if needed

### Leptos: Why 0.8.12?

- **Stability**: Latest stable release
- **WASM support**: Full CSR (client-side rendering) support
- **Component stability**: Core components stable
- **Routing**: Mature routing library included

---

## Dependency Rules

### Rule 1: Use Root Workspace Dependencies

All internal crates must specify dependencies via:

```toml
# ✅ Correct: Use workspace inheritance
[dependencies]
tokio = { workspace = true }
serde = { workspace = true }

# ❌ Wrong: Duplicate version specification
[dependencies]
tokio = "1.48"  # Don't do this, use workspace = true
```

### Rule 2: Feature Coordination

When using optional features, ensure consistency:

```toml
# ✅ Correct: Explicit features match canonical registry
[dependencies]
serde = { workspace = true, features = ["derive"] }

# ❌ Wrong: Missing features from canonical registry
[dependencies]
serde = { workspace = true }  # Missing derive feature
```

### Rule 3: No Version Overrides

Never override workspace dependency versions in individual crates:

```toml
# ❌ Wrong: Causes conflicts
[dependencies]
tokio = "1.45"  # Different from workspace 1.48

# ✅ Correct: Use workspace version
[dependencies]
tokio = { workspace = true }
```

### Rule 4: Shared Library Independence

Shared libraries should remain portable:

```toml
# shared/rust-api/shared-api-lib/Cargo.toml
[dependencies]
# These can be specified independently for portability
# But dependency-manager validates they match canonical registry
axum = "0.8"
tokio = "1.48"

# When used in monorepo, these versions must match canonical registry
```

---

## Managing Dependencies

### Adding New Dependencies

**Process**:
1. **Evaluate necessity**: Do we really need this?
2. **Check alternatives**: Use existing dependencies if possible
3. **Research stability**: Check GitHub, reviews, update frequency
4. **Add to canonical registry**: Update this document (Tier 1, 2, or 3)
5. **Add to root workspace**: Add to `Cargo.toml [workspace.dependencies]`
6. **Use in crates**: Add to crate with `{ workspace = true }`
7. **Test**: Run `cargo test --workspace`
8. **Document**: Explain in this file why it was added

**Example**:

```toml
# .claude/DEPENDENCIES.md - Add to appropriate tier
| **my-new-lib** | `1.0` | `["feature"]` | Brief rationale for why needed |

# Cargo.toml - Add to [workspace.dependencies]
my-new-lib = { version = "1.0", features = ["feature"] }

# syntaxis-core/Cargo.toml (or relevant crate)
my-new-lib = { workspace = true }
```

### Updating Existing Dependencies

**Process**:
1. **Check for breaking changes**: Review release notes
2. **Test locally**: `cargo update -p my-lib && cargo test --workspace`
3. **Plan migration**: If breaking changes, create task
4. **Update DEPENDENCIES.md**: Document new version and changes
5. **Update Cargo.toml**: Change version in `[workspace.dependencies]`
6. **Run full validation**: `just check-all`

**Commands**:

```bash
# Check outdated dependencies
cargo outdated

# Update one dependency
cargo update -p tokio

# Update all dependencies
cargo update

# Check security vulnerabilities
cargo audit

# Fix security issues
cargo audit fix
```

### Removing Dependencies

**Process**:
1. **Find usages**: `cargo tree -d my-lib`
2. **Remove from all crates**: Update all `Cargo.toml` files
3. **Remove from workspace**: Delete from `[workspace.dependencies]`
4. **Update this document**: Remove from DEPENDENCIES.md
5. **Test**: `cargo test --workspace`

---

## Synchronization with dependency-manager

### Validation

The `dependency-manager` tool validates that all crates use canonical versions:

```bash
# Check if all dependencies match canonical registry
dependency-manager validate

# Show detailed mismatches
dependency-manager detect

# Show canonical registry
dependency-manager registry
```

### Automatic Synchronization

```bash
# Interactive: Review and approve each change
dependency-manager sync --interactive

# Batch: Update all mismatches
dependency-manager sync --batch
```

### Integration with Git

Pre-commit hook automatically validates:

```bash
# In .git/hooks/pre-commit
dependency-manager validate
```

---

## Testing After Dependency Changes

Always run full validation after updating dependencies:

```bash
# Clean rebuild
cargo clean
cargo check --workspace

# Test all crates
cargo test --workspace --lib
cargo test --workspace          # Including integration tests

# Lint and security
cargo clippy --all-targets
cargo audit

# Or use Justfile recipe
just check-all
```

---

## Security Considerations

### Regular Audits

```bash
# Check for known vulnerabilities
cargo audit

# Fix automatically (if available)
cargo audit fix

# Check specific crate
cargo audit -p syntaxis-core
```

### Dependency Trust

When adding new dependencies:

- ✅ Prefer well-maintained libraries
- ✅ Check update frequency (should be recent)
- ✅ Review GitHub repository health
- ✅ Check for security audits or certifications
- ❌ Avoid unmaintained or abandoned projects
- ❌ Avoid highly experimental or unproven libraries

### Feature Security

Some dependencies have security implications:

- `jsonwebtoken`: Must use `aws_lc_rs` for cryptography safety
- `rustls`: Modern TLS (prefer over OpenSSL)
- All crypto: Keep updated for latest security patches

---

## Performance Considerations

### Heavy Dependencies

- **leptos**: Adds 5-10 seconds to compile time (WASM build)
- **criterion**: Only use in `[dev-dependencies]`
- **ratatui beta**: Slightly longer compile than stable

### Optimizing Compile Time

Disable unnecessary features:

```toml
# Instead of:
[dependencies]
tokio = { version = "1.48", features = ["full"] }

# Could use minimal features:
[dependencies]
tokio = { version = "1.48", features = ["rt", "macros", "sync"] }
```

However, syntaxis uses `["full"]` for flexibility.

---

## Current Status

### Version Alignment

- ✅ Most dependencies aligned across workspace
- ⚠️ **jsonwebtoken**: 9.3 (root) vs 10.2 (syntaxis) - **BEING FIXED**
- ⚠️ **tokio**: "1" (flexible) vs "1.48" (pinned) - **BEING STANDARDIZED**

### Compliance

- ✅ No unsafe code (`#![forbid(unsafe_code)]`)
- ✅ All features coordinated
- ✅ No version conflicts in compiled output
- ⚠️ dependency-manager integration pending

---

## Maintenance Schedule

| Task | Frequency | Owner |
|------|-----------|-------|
| Check for vulnerabilities | Weekly | CI/CD |
| Review outdated versions | Monthly | Development Team |
| Security audit reports | Monthly | Development Team |
| Major version evaluations | Quarterly | Architecture Team |
| DEPENDENCIES.md updates | As needed | Committer |

---

## References

- **Cargo.toml**: Root workspace definition
- **PROJECT_RULES.md**: Architecture and module organization
- **CODE_STANDARDS.md**: Build and testing standards
- **dependency-manager**: External tool for validation
- **Cargo Book**: https://doc.rust-lang.org/cargo/

---

**Last Updated**: 2025-11-15
**Next Review**: 2025-12-15