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]:

[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:

# ✅ 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:

# ✅ 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:

# ❌ 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:

# 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:

# .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:

# 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:

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

# Show detailed mismatches
dependency-manager detect

# Show canonical registry
dependency-manager registry

Automatic Synchronization

# 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:

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

---

Testing After Dependency Changes

Always run full validation after updating dependencies:

# 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

# 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:

# 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