studio/marathon
2
0
Fork 0
Code Issues 121 Pull Requests Actions Packages Projects Releases Wiki Activity

chore: removed bincode for rkyv

Browse Source 
Signed-off-by: Sienna Meridian Satterwhite <sienna@r3t.io>
This commit is contained in:
Sienna Meridian Satterwhite
2025-12-17 19:20:34 +00:00
parent 6b994aa7c4
commit c57a9c0787
47 changed files with 2728 additions and 1697 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.serena/.gitignore vendored Normal file
View File

@@ -0,0 +1 @@
/cache

294
.serena/memories/code_style_conventions.md Normal file
View File

@@ -0,0 +1,294 @@
# Code Style & Conventions
## Rust Style Configuration
The project uses **rustfmt** with a custom configuration (`rustfmt.toml`):
### Key Formatting Rules
- **Edition**: 2021
- **Braces**: `PreferSameLine` for structs/enums, `AlwaysSameLine` for control flow
- **Function Layout**: `Tall` (each parameter on its own line for long signatures)
- **Single-line Functions**: Disabled (`fn_single_line = false`)
- **Imports**:
- Grouping: `StdExternalCrate` (std, external, then local)
- Layout: `Vertical` (one import per line)
- Granularity: `Crate` level
- Reorder: Enabled
- **Comments**:
- Width: 80 characters
- Wrapping: Enabled
- Format code in doc comments: Enabled
- **Doc Attributes**: Normalized (`normalize_doc_attributes = true`)
- **Impl Items**: Reordered (`reorder_impl_items = true`)
- **Match Arms**: Leading pipes always shown
- **Hex Literals**: Lowercase
### Applying Formatting
```bash
# Format all code
cargo fmt
# Check without modifying
cargo fmt -- --check
```
## Naming Conventions
### Rust Standard Conventions
- **Types** (structs, enums, traits): `PascalCase`
- Example: `EngineBridge`, `PersistenceConfig`, `SessionId`
- **Functions & Methods**: `snake_case`
- Example: `run_executor()`, `get_database_path()`
- **Constants**: `SCREAMING_SNAKE_CASE`
- Example: `APP_NAME`, `DEFAULT_BUFFER_SIZE`
- **Variables**: `snake_case`
- Example: `engine_bridge`, `db_path_str`
- **Modules**: `snake_case`
- Example: `debug_ui`, `engine_bridge`
- **Crates**: `kebab-case` in Cargo.toml, `snake_case` in code
- Example: `sync-macros` → `sync_macros`
### Project-Specific Patterns
- **Platform modules**: `platform/desktop/`, `platform/ios/`
- **Plugin naming**: Suffix with `Plugin` (e.g., `EngineBridgePlugin`, `CameraPlugin`)
- **Resource naming**: Prefix with purpose (e.g., `PersistenceConfig`, `SessionManager`)
- **System naming**: Suffix with `_system` for Bevy systems
- **Bridge pattern**: Use `Bridge` suffix for inter-component communication (e.g., `EngineBridge`)
## Code Organization
### Module Structure
```rust
// Public API first
pub mod engine;
pub mod networking;
pub mod persistence;
// Internal modules
mod debug_ui;
mod platform;
// Re-exports for convenience
pub use engine::{EngineCore, EngineBridge};
```
### Import Organization
```rust
// Standard library
use std::sync::Arc;
use std::thread;
// External crates (grouped by crate)
use bevy::prelude::*;
use serde::{Deserialize, Serialize};
use tokio::runtime::Runtime;
// Internal crates
use libmarathon::engine::EngineCore;
use libmarathon::platform;
// Local modules
use crate::camera::*;
use crate::debug_ui::DebugUiPlugin;
```
## Documentation
### Doc Comments
- Use `///` for public items
- Use `//!` for module-level documentation
- Include examples where helpful
- Document panics, errors, and safety considerations
```rust
/// Creates a new engine bridge for communication between Bevy and EngineCore.
///
/// # Returns
///
/// A tuple of `(EngineBridge, EngineHandle)` where the bridge goes to Bevy
/// and the handle goes to EngineCore.
///
/// # Examples
///
/// ```no_run
/// let (bridge, handle) = EngineBridge::new();
/// app.insert_resource(bridge);
/// // spawn EngineCore with handle
/// ```
pub fn new() -> (EngineBridge, EngineHandle) {
// ...
}
```
### Code Comments
- Keep line comments at 80 characters or less
- Explain *why*, not *what* (code should be self-documenting for the "what")
- Use `// TODO:` for temporary code that needs improvement
- Use `// SAFETY:` before unsafe blocks to explain invariants
## Error Handling
### Library Code (libmarathon)
- Use `thiserror` for custom error types
- Return `Result<T, Error>` from fallible functions
- Provide context with error chains
```rust
use thiserror::Error;
#[derive(Error, Debug)]
pub enum EngineError {
#[error("failed to connect to peer: {0}")]
ConnectionFailed(String),
#[error("database error: {0}")]
Database(#[from] rusqlite::Error),
}
```
### Application Code (app)
- Use `anyhow::Result` for application-level error handling
- Add context with `.context()` or `.with_context()`
```rust
use anyhow::{Context, Result};
fn load_config() -> Result<Config> {
let path = get_config_path()
.context("failed to determine config path")?;
std::fs::read_to_string(&path)
.with_context(|| format!("failed to read config from {:?}", path))?
// ...
}
```
## Async/Await Style
### Tokio Runtime Usage
- Spawn blocking tasks in background threads
- Use `tokio::spawn` for async tasks
- Prefer `async fn` over `impl Future`
```rust
// Good: Clear async function
async fn process_events(&mut self) -> Result<()> {
// ...
}
// Background task spawning
std::thread::spawn(move || {
let rt = tokio::runtime::Runtime::new().unwrap();
rt.block_on(async {
core.run().await;
});
});
```
## Testing Conventions
### Test Organization
- Unit tests: In same file as code (`#[cfg(test)] mod tests`)
- Integration tests: In `tests/` directory
- Benchmarks: In `benches/` directory
### Test Naming
- Use descriptive names: `test_sync_between_two_nodes`
- Use `should_` prefix for behavior tests: `should_reject_invalid_input`
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_engine_bridge_creation() {
let (bridge, handle) = EngineBridge::new();
// ...
}
#[tokio::test]
async fn should_sync_state_across_peers() {
// ...
}
}
```
## Platform-Specific Code
### Feature Gates
```rust
// iOS-specific code
#[cfg(target_os = "ios")]
use tracing_oslog::OsLogger;
// Desktop-specific code
#[cfg(not(target_os = "ios"))]
use tracing_subscriber::fmt;
```
### Platform Modules
- Keep platform-specific code in `platform/` modules
- Provide platform-agnostic interfaces when possible
- Use feature flags: `desktop`, `ios`, `headless`
## Logging
### Use Structured Logging
```rust
use tracing::{debug, info, warn, error};
// Good: Structured with context
info!(path = %db_path, "opening database");
debug!(count = peers.len(), "connected to peers");
// Avoid: Plain string
info!("Database opened at {}", db_path);
```
### Log Levels
- `error!`: System failures requiring immediate attention
- `warn!`: Unexpected conditions that are handled
- `info!`: Important state changes and milestones
- `debug!`: Detailed diagnostic information
- `trace!`: Very verbose, rarely needed
## RFCs and Design Documentation
### When to Write an RFC
- Architectural decisions affecting multiple parts
- Choosing between significantly different approaches
- Introducing new protocols or APIs
- Making breaking changes
### RFC Structure (see `docs/rfcs/README.md`)
- Narrative-first explanation
- Trade-offs and alternatives
- API examples (not full implementations)
- Open questions
- Success criteria
## Git Commit Messages
### Format
```
Brief summary (50 chars or less)
More detailed explanation if needed. Wrap at 72 characters.
- Use bullet points for multiple changes
- Reference issue numbers: #123
Explains trade-offs, alternatives considered, and why this approach
was chosen.
```
### Examples
```
Add CRDT synchronization over iroh-gossip
Implements the protocol described in RFC 0001. Uses vector clocks
for causal ordering and merkle trees for efficient reconciliation.
- Add VectorClock type
- Implement GossipBridge for peer communication
- Add integration tests for two-peer sync
```

77
.serena/memories/codebase_structure.md Normal file
View File

@@ -0,0 +1,77 @@
# Codebase Structure
## Workspace Organization
```
aspen/
├── crates/
│ ├── app/ # Main application
│ │ ├── src/
│ │ │ ├── main.rs # Entry point
│ │ │ ├── camera.rs # Camera system
│ │ │ ├── cube.rs # 3D cube demo
│ │ │ ├── debug_ui.rs # Debug overlays
│ │ │ ├── engine_bridge.rs # Bridge to EngineCore
│ │ │ ├── input/ # Input handling
│ │ │ ├── rendering.rs # Rendering setup
│ │ │ ├── selection.rs # Object selection
│ │ │ ├── session.rs # Session management
│ │ │ ├── session_ui.rs # Session UI
│ │ │ └── setup.rs # App initialization
│ │ └── Cargo.toml
│ │
│ ├── libmarathon/ # Core library
│ │ ├── src/
│ │ │ ├── lib.rs # Library root
│ │ │ ├── sync.rs # Synchronization primitives
│ │ │ ├── engine/ # Core engine logic
│ │ │ ├── networking/ # P2P networking, gossip
│ │ │ ├── persistence/ # Database and storage
│ │ │ ├── platform/ # Platform-specific code
│ │ │ │ ├── desktop/ # macOS executor
│ │ │ │ └── ios/ # iOS executor
│ │ │ └── debug_ui/ # Debug UI components
│ │ └── Cargo.toml
│ │
│ ├── sync-macros/ # Procedural macros for sync
│ │ └── src/lib.rs
│ │
│ └── xtask/ # Build automation
│ ├── src/main.rs
│ └── README.md
│
├── scripts/
│ └── ios/ # iOS-specific build scripts
│ ├── Info.plist # iOS app metadata
│ ├── Entitlements.plist # App capabilities
│ ├── deploy-simulator.sh # Simulator deployment
│ └── build-simulator.sh # Build for simulator
│
├── docs/
│ └── rfcs/ # Architecture RFCs
│ ├── README.md
│ ├── 0001-crdt-gossip-sync.md
│ ├── 0002-persistence-strategy.md
│ ├── 0003-sync-abstraction.md
│ ├── 0004-session-lifecycle.md
│ ├── 0005-spatial-audio-system.md
│ └── 0006-agent-simulation-architecture.md
│
├── .github/
│ └── ISSUE_TEMPLATE/ # GitHub issue templates
│ ├── bug_report.yml
│ ├── feature.yml
│ ├── task.yml
│ ├── epic.yml
│ └── support.yml
│
├── Cargo.toml # Workspace configuration
├── Cargo.lock # Dependency lock file
└── rustfmt.toml # Code formatting rules
```
## Key Patterns
- **ECS Architecture**: Uses Bevy's Entity Component System
- **Platform Abstraction**: Separate executors for desktop/iOS
- **Engine-UI Separation**: `EngineCore` runs in background thread, communicates via `EngineBridge`
- **CRDT-based Sync**: All shared state uses CRDTs for conflict-free merging
- **RFC-driven Design**: Major decisions documented in `docs/rfcs/`

59
.serena/memories/github_labels.md Normal file
View File

@@ -0,0 +1,59 @@
# GitHub Labels
This file contains the standard label configuration for r3t-studios repositories.
## Labels from marathon repository
These labels are currently defined in the marathon repository:
### Area Labels
| Name | Color | Description |
|------|-------|-------------|
| `area/core` | `#0052CC` | Foundation systems, memory management, math libraries, data structures, core utilities |
| `area/rendering` | `#0E8A16` | Graphics pipeline, Bevy rendering, shaders, materials, lighting, cameras, meshes, textures |
| `area/audio` | `#1D76DB` | Spatial audio engine, sound playback, audio mixing, music systems, 3D audio positioning |
| `area/networking` | `#5319E7` | iroh P2P, CRDT sync, gossip protocol, network replication, connection management |
| `area/platform` | `#0075CA` | iOS/macOS platform code, cross-platform abstractions, input handling, OS integration |
| `area/simulation` | `#FBCA04` | Agent systems, NPC behaviors, AI, game mechanics, interactions, simulation logic |
| `area/content` | `#C5DEF5` | Art assets, models, textures, audio files, dialogue trees, narrative content, game data |
| `area/ui-ux` | `#D4C5F9` | User interface, menus, HUD elements, input feedback, screen layouts, navigation |
| `area/tooling` | `#D93F0B` | Build systems, CI/CD pipelines, development tools, code generation, testing infrastructure |
| `area/docs` | `#0075CA` | Documentation, technical specs, RFCs, architecture decisions, API docs, tutorials, guides |
| `area/infrastructure` | `#E99695` | Deployment pipelines, hosting, cloud services, monitoring, logging, DevOps, releases |
| `area/rfc` | `#FEF2C0` | RFC proposals, design discussions, architecture planning, feature specifications |
## Labels referenced in issue templates but not yet created
The following labels are referenced in issue templates but don't exist in the repository yet:
| Name | Used In | Suggested Color | Description |
|------|---------|-----------------|-------------|
| `epic` | epic.yml | `#3E4B9E` | Large body of work spanning multiple features |
## Command to create all labels in a new repository
```bash
# Area labels
gh label create "area/core" --description "Foundation systems, memory management, math libraries, data structures, core utilities" --color "0052CC"
gh label create "area/rendering" --description "Graphics pipeline, Bevy rendering, shaders, materials, lighting, cameras, meshes, textures" --color "0E8A16"
gh label create "area/audio" --description "Spatial audio engine, sound playback, audio mixing, music systems, 3D audio positioning" --color "1D76DB"
gh label create "area/networking" --description "iroh P2P, CRDT sync, gossip protocol, network replication, connection management" --color "5319E7"
gh label create "area/platform" --description "iOS/macOS platform code, cross-platform abstractions, input handling, OS integration" --color "0075CA"
gh label create "area/simulation" --description "Agent systems, NPC behaviors, AI, game mechanics, interactions, simulation logic" --color "FBCA04"
gh label create "area/content" --description "Art assets, models, textures, audio files, dialogue trees, narrative content, game data" --color "C5DEF5"
gh label create "area/ui-ux" --description "User interface, menus, HUD elements, input feedback, screen layouts, navigation" --color "D4C5F9"
gh label create "area/tooling" --description "Build systems, CI/CD pipelines, development tools, code generation, testing infrastructure" --color "D93F0B"
gh label create "area/docs" --description "Documentation, technical specs, RFCs, architecture decisions, API docs, tutorials, guides" --color "0075CA"
gh label create "area/infrastructure" --description "Deployment pipelines, hosting, cloud services, monitoring, logging, DevOps, releases" --color "E99695"
gh label create "area/rfc" --description "RFC proposals, design discussions, architecture planning, feature specifications" --color "FEF2C0"
# Issue type labels
gh label create "epic" --description "Large body of work spanning multiple features" --color "3E4B9E"
```
## Notes
- The marathon repository has 12 labels defined, all with the `area/` prefix
- The `epic` label is referenced in the epic.yml issue template but hasn't been created yet in either marathon or aspen
- All area labels use distinct colors for easy visual identification

457
.serena/memories/macos_system_commands.md Normal file
View File

@@ -0,0 +1,457 @@
# macOS (Darwin) System Commands
This document covers macOS-specific system commands and utilities that may differ from standard Unix/Linux systems.
## File System Operations
### Finding Files
```bash
# Standard Unix find (works on macOS)
find . -name "*.rs"
find . -type f -name "Cargo.toml"
# macOS Spotlight search (faster for indexed content)
mdfind -name "rustfmt.toml"
mdfind "kind:rust-source"
# Locate database (if enabled)
locate pattern
```
### Listing & Viewing
```bash
# List with details
ls -la
ls -lh # human-readable sizes
ls -lhS # sorted by size
ls -lht # sorted by modification time
# View file contents
cat file.txt
head -20 file.txt
tail -50 file.txt
less file.txt # paginated view
# Quick Look (macOS-specific)
qlmanage -p file.txt # preview file
```
### Directory Navigation
```bash
cd /path/to/directory
cd ~ # home directory
cd - # previous directory
pwd # print working directory
pushd /path # push to directory stack
popd # pop from directory stack
```
## Text Processing
### Searching in Files
```bash
# grep (standard)
grep -r "pattern" .
grep -i "pattern" file.txt # case-insensitive
grep -n "pattern" file.txt # with line numbers
grep -A 5 "pattern" file.txt # 5 lines after match
grep -B 5 "pattern" file.txt # 5 lines before match
# ripgrep (if installed - faster and better)
rg "pattern"
rg -i "pattern" # case-insensitive
rg -t rust "pattern" # only Rust files
```
### Text Manipulation
```bash
# sed (stream editor) - macOS uses BSD sed
sed -i '' 's/old/new/g' file.txt # note the '' for in-place edit
sed 's/pattern/replacement/' file.txt
# awk
awk '{print $1}' file.txt
# cut
cut -d',' -f1,3 file.csv
```
## Process Management
### Viewing Processes
```bash
# List processes
ps aux
ps aux | grep cargo
# Interactive process viewer
top
htop # if installed (better)
# Activity Monitor (GUI)
open -a "Activity Monitor"
```
### Process Control
```bash
# Kill process
kill PID
kill -9 PID # force kill
killall process_name
# Background/foreground
command & # run in background
fg # bring to foreground
bg # continue in background
Ctrl+Z # suspend foreground process
```
## Network
### Network Info
```bash
# IP address
ifconfig
ipconfig getifaddr en0 # specific interface
# Network connectivity
ping google.com
traceroute google.com
# DNS lookup
nslookup domain.com
dig domain.com
# Network statistics
netstat -an
lsof -i # list open network connections
```
### Port Management
```bash
# Check what's using a port
lsof -i :8080
lsof -i tcp:3000
# Kill process using port
lsof -ti:8080 | xargs kill
```
## File Permissions
### Basic Permissions
```bash
# Change permissions
chmod +x script.sh # make executable
chmod 644 file.txt # rw-r--r--
chmod 755 dir/ # rwxr-xr-x
# Change ownership
chown user:group file
chown -R user:group directory/
# View permissions
ls -l
stat file.txt # detailed info
```
### Extended Attributes (macOS-specific)
```bash
# List extended attributes
xattr -l file
# Remove quarantine attribute
xattr -d com.apple.quarantine file
# Clear all extended attributes
xattr -c file
```
## Disk & Storage
### Disk Usage
```bash
# Disk space
df -h
df -h /
# Directory size
du -sh directory/
du -h -d 1 . # depth 1
# Sort by size
du -sh * | sort -h
```
### Disk Utility
```bash
# Verify disk
diskutil verifyVolume /
diskutil list
# Mount/unmount
diskutil mount diskName
diskutil unmount diskName
```
## Package Management
### Homebrew (common on macOS)
```bash
# Install package
brew install package-name
# Update Homebrew
brew update
# Upgrade packages
brew upgrade
# List installed
brew list
# Search packages
brew search pattern
```
### Mac App Store
```bash
# List updates
softwareupdate --list
# Install updates
softwareupdate --install --all
```
## System Information
### System Details
```bash
# macOS version
sw_vers
sw_vers -productVersion
# System profiler
system_profiler SPHardwareDataType
system_profiler SPSoftwareDataType
# Kernel info
uname -a
```
### Hardware Info
```bash
# CPU info
sysctl -n machdep.cpu.brand_string
sysctl hw
# Memory
top -l 1 | grep PhysMem
# Disk info
diskutil info /
```
## Environment & Shell
### Environment Variables
```bash
# View all
env
printenv
# Set variable
export VAR_NAME=value
# Shell config files
~/.zshrc # Zsh (default on modern macOS)
~/.bashrc # Bash
~/.profile # Login shell
```
### Path Management
```bash
# View PATH
echo $PATH
# Add to PATH (in ~/.zshrc or ~/.bashrc)
export PATH="/usr/local/bin:$PATH"
# Which command
which cargo
which rustc
```
## Archives & Compression
### Tar
```bash
# Create archive
tar -czf archive.tar.gz directory/
# Extract archive
tar -xzf archive.tar.gz
# List contents
tar -tzf archive.tar.gz
```
### Zip
```bash
# Create zip
zip -r archive.zip directory/
# Extract zip
unzip archive.zip
# List contents
unzip -l archive.zip
```
## Clipboard (macOS-specific)
```bash
# Copy to clipboard
echo "text" | pbcopy
cat file.txt | pbcopy
# Paste from clipboard
pbpaste
pbpaste > file.txt
```
## Notifications (macOS-specific)
```bash
# Display notification
osascript -e 'display notification "Message" with title "Title"'
# Alert dialog
osascript -e 'display dialog "Message" with title "Title"'
```
## Xcode & iOS Development
### Xcode Command Line Tools
```bash
# Install command line tools
xcode-select --install
# Show active developer directory
xcode-select -p
# Switch Xcode version
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```
### iOS Simulator
```bash
# List simulators
xcrun simctl list devices
# Boot simulator
xcrun simctl boot "iPad Pro 12.9-inch M2"
# Open Simulator app
open -a Simulator
# Install app
xcrun simctl install <device-uuid> path/to/app.app
# Launch app
xcrun simctl launch <device-uuid> bundle.id
# View logs
xcrun simctl spawn <device-uuid> log stream
```
### Physical Device
```bash
# List connected devices
xcrun devicectl list devices
# Install app
xcrun devicectl device install app --device <device-id> path/to/app.app
# Launch app
xcrun devicectl device process launch --device <device-id> bundle.id
# View logs
xcrun devicectl device stream log --device <device-id>
```
### Code Signing
```bash
# List signing identities
security find-identity -v -p codesigning
# Sign application
codesign -s "Developer ID" path/to/app.app
# Verify signature
codesign -vv path/to/app.app
```
## macOS-Specific Differences from Linux
### Key Differences
1. **sed**: Requires empty string for in-place edit: `sed -i '' ...`
2. **find**: Uses BSD find (slightly different options)
3. **date**: Different format options than GNU date
4. **readlink**: Use `greadlink` (if coreutils installed) for `-f` flag
5. **stat**: Different output format than GNU stat
6. **grep**: BSD grep (consider installing `ggrep` for GNU grep)
### GNU Tools via Homebrew
```bash
# Install GNU coreutils
brew install coreutils
# Then use with 'g' prefix
gls, gcp, gmv, grm, greadlink, gdate, etc.
```
## Useful macOS Shortcuts
### Terminal Shortcuts
- `Cmd+K` - Clear terminal
- `Cmd+T` - New tab
- `Cmd+N` - New window
- `Cmd+W` - Close tab
- `Cmd+,` - Preferences
### Command Line Shortcuts
- `Ctrl+A` - Beginning of line
- `Ctrl+E` - End of line
- `Ctrl+U` - Delete to beginning
- `Ctrl+K` - Delete to end
- `Ctrl+R` - Search history
- `Ctrl+C` - Cancel command
- `Ctrl+D` - Exit shell
- `Ctrl+Z` - Suspend process
## Quick Reference
### Most Common for Aspen Development
```bash
# Find Rust files
find . -name "*.rs"
# Search in Rust files
grep -r "pattern" crates/
# Check what's using a port
lsof -i :8080
# View disk space
df -h
# View process list
ps aux | grep cargo
# View logs
log stream --predicate 'process == "app"'
# Xcode simulators
xcrun simctl list devices available
```

27
.serena/memories/project_overview.md Normal file
View File

@@ -0,0 +1,27 @@
# Project Overview: Aspen
## Purpose
Aspen (formerly known as Lonni) is a **cross-platform real-time collaborative application** built for macOS and iPad. It demonstrates real-time CRDT (Conflict-free Replicated Data Type) synchronization with Apple Pencil input support.
## Key Features
- Real-time collaborative drawing/interaction with Apple Pencil support
- P2P synchronization using CRDTs over iroh-gossip protocol
- Cross-platform: macOS desktop and iOS/iPadOS
- 3D rendering using Bevy game engine
- Persistent local storage with SQLite
- Session management for multi-user collaboration
## Target Platforms
- **macOS** (desktop application)
- **iOS/iPadOS** (with Apple Pencil support)
- Uses separate executors for each platform
## Architecture
The application uses a **workspace structure** with multiple crates:
- `app` - Main application entry point and UI
- `libmarathon` - Core library with engine, networking, persistence
- `sync-macros` - Procedural macros for synchronization
- `xtask` - Build automation tasks
## Development Status
Active development with RFCs for major design decisions. See `docs/rfcs/` for architectural documentation.

237
.serena/memories/suggested_commands.md Normal file
View File

@@ -0,0 +1,237 @@
# Suggested Commands for Aspen Development
## Build & Run Commands
### iOS Simulator (Primary Development Target)
```bash
# Build, deploy, and run on iOS Simulator (most common)
cargo xtask ios-run
# Build only (release mode)
cargo xtask ios-build
# Build in debug mode
cargo xtask ios-build --debug
# Deploy to specific device
cargo xtask ios-deploy --device "iPad Air (5th generation)"
# Run with debug mode and custom device
cargo xtask ios-run --debug --device "iPhone 15 Pro"
# Build and deploy to physical iPad
cargo xtask ios-device
```
### Desktop (macOS)
```bash
# Run on macOS desktop
cargo run --package app --features desktop
# Run in release mode
cargo run --package app --features desktop --release
```
## Testing
```bash
# Run all tests
cargo test
# Run tests for specific package
cargo test --package libmarathon
cargo test --package app
# Run integration tests
cargo test --test sync_integration
# Run with specific test
cargo test test_sync_between_two_nodes
# Run tests with logging output
RUST_LOG=debug cargo test -- --nocapture
```
## Code Quality
### Formatting
```bash
# Format all code (uses rustfmt.toml configuration)
cargo fmt
# Check formatting without modifying files
cargo fmt -- --check
```
### Linting
```bash
# Run clippy for all crates
cargo clippy --all-targets --all-features
# Run clippy with fixes
cargo clippy --fix --allow-dirty --allow-staged
# Strict clippy checks
cargo clippy -- -D warnings
```
### Building
```bash
# Build all crates
cargo build
# Build in release mode
cargo build --release
# Build specific package
cargo build --package libmarathon
# Build for iOS target
cargo build --target aarch64-apple-ios --release
cargo build --target aarch64-apple-ios-sim --release
```
## Cleaning
```bash
# Clean build artifacts
cargo clean
# Clean specific package
cargo clean --package xtask
# Clean and rebuild
cargo clean && cargo build
```
## Benchmarking
```bash
# Run benchmarks
cargo bench
# Run specific benchmark
cargo bench --bench write_buffer
cargo bench --bench vector_clock
```
## Documentation
```bash
# Generate and open documentation
cargo doc --open
# Generate docs for all dependencies
cargo doc --open --document-private-items
```
## Dependency Management
```bash
# Update dependencies
cargo update
# Check for outdated dependencies
cargo outdated
# Show dependency tree
cargo tree
# Check specific dependency
cargo tree -p iroh
```
## iOS-Specific Commands
### Simulator Management
```bash
# List available simulators
xcrun simctl list devices available
# Boot a specific simulator
xcrun simctl boot "iPad Pro 12.9-inch M2"
# Open Simulator app
open -a Simulator
# View simulator logs
xcrun simctl spawn <device-uuid> log stream --predicate 'processImagePath contains "Aspen"'
```
### Device Management
```bash
# List connected devices
xcrun devicectl list devices
# View device logs
xcrun devicectl device stream log --device <device-id> --predicate 'process == "app"'
```
## Git Commands (macOS-specific notes)
```bash
# Standard git commands work on macOS
git status
git add .
git commit -m "message"
git push
# View recent commits
git log --oneline -10
# Check current branch
git branch
```
## System Commands (macOS)
```bash
# Find files (macOS has both find and mdfind)
find . -name "*.rs"
mdfind -name "rustfmt.toml"
# Search in files
grep -r "pattern" crates/
rg "pattern" crates/ # if ripgrep is installed
# List files
ls -la
ls -lh # human-readable sizes
# Navigate
cd crates/app
pwd
# View file contents
cat Cargo.toml
head -20 src/main.rs
tail -50 Cargo.lock
```
## Common Workflows
### After Making Changes
```bash
# 1. Format code
cargo fmt
# 2. Run clippy
cargo clippy --all-targets
# 3. Run tests
cargo test
# 4. Test on simulator
cargo xtask ios-run
```
### Adding a New Feature
```bash
# 1. Create RFC if it's a major change
# edit docs/rfcs/NNNN-feature-name.md
# 2. Implement
# edit crates/.../src/...
# 3. Add tests
# edit crates/.../tests/...
# 4. Update documentation
cargo doc --open
# 5. Run full validation
cargo fmt && cargo clippy && cargo test && cargo xtask ios-run
```

211
.serena/memories/task_completion_checklist.md Normal file
View File

@@ -0,0 +1,211 @@
# Task Completion Checklist
When completing a task in Aspen, follow these steps to ensure code quality and consistency.
## Pre-Commit Checklist
### 1. Code Formatting
```bash
cargo fmt
```
- Formats all code according to `rustfmt.toml`
- Must pass before committing
- Check with: `cargo fmt -- --check`
### 2. Linting
```bash
cargo clippy --all-targets --all-features
```
- Checks for common mistakes and anti-patterns
- Address all warnings
- For strict mode: `cargo clippy -- -D warnings`
### 3. Type Checking & Compilation
```bash
cargo check
cargo build
```
- Ensure code compiles without errors
- Check both debug and release if performance-critical:
```bash
cargo build --release
```
### 4. Testing
```bash
# Run all tests
cargo test
# Run with output
cargo test -- --nocapture
# Run integration tests
cargo test --test sync_integration
```
- All existing tests must pass
- Add new tests for new functionality
- Integration tests for cross-component features
### 5. Platform-Specific Testing
#### iOS Simulator
```bash
cargo xtask ios-run
```
- Test on iOS Simulator (default: iPad Pro 12.9-inch M2)
- Verify Apple Pencil interactions if applicable
- Check logging output for errors
#### Physical Device (if iOS changes)
```bash
cargo xtask ios-device
```
- Test on actual iPad if Apple Pencil features are involved
- Verify Developer Mode is enabled
#### macOS Desktop
```bash
cargo run --package app --features desktop
```
- Test desktop functionality
- Verify window handling and input
### 6. Documentation
```bash
cargo doc --open
```
- Add doc comments to public APIs
- Update module-level documentation if structure changed
- Verify generated docs render correctly
- Update RFCs if architectural changes were made
## Specific Checks by Change Type
### For New Features
- [ ] Write RFC if architectural change (see `docs/rfcs/README.md`)
- [ ] Add public API documentation
- [ ] Add examples in doc comments
- [ ] Write integration tests
- [ ] Test on both macOS and iOS if cross-platform
- [ ] Update relevant memory files if workflow changes
### For Bug Fixes
- [ ] Add regression test
- [ ] Document the bug in commit message
- [ ] Verify fix on affected platform(s)
- [ ] Check for similar bugs in related code
### For Performance Changes
- [ ] Run benchmarks before and after
```bash
cargo bench
```
- [ ] Document performance impact in commit message
- [ ] Test on debug and release builds
### For Refactoring
- [ ] Ensure all tests still pass
- [ ] Verify no behavioral changes
- [ ] Update related documentation
- [ ] Check that clippy warnings didn't increase
### For Dependency Updates
- [ ] Update `Cargo.toml` (workspace or specific crate)
- [ ] Run `cargo update`
- [ ] Check for breaking changes in changelog
- [ ] Re-run full test suite
- [ ] Test on both platforms
## Before Pushing
### Final Validation
```bash
# One-liner for comprehensive check
cargo fmt && cargo clippy --all-targets && cargo test && cargo xtask ios-run
```
### Git Checks
- [ ] Review `git diff` for unintended changes
- [ ] Ensure sensitive data isn't included
- [ ] Write clear commit message (see code_style_conventions.md)
- [ ] Verify correct branch
### Issue Tracking
- [ ] Update issue status (use GitHub issue templates)
- [ ] Link commits to issues in commit message
- [ ] Update project board if using one
## Platform-Specific Considerations
### iOS Changes
- [ ] Test on iOS Simulator
- [ ] Verify Info.plist changes if app metadata changed
- [ ] Check Entitlements.plist if permissions changed
- [ ] Test with Apple Pencil if input handling changed
- [ ] Verify app signing (bundle ID: `G872CZV7WG.aspen`)
### Networking Changes
- [ ] Test P2P connectivity on local network
- [ ] Verify gossip propagation with multiple peers
- [ ] Check CRDT merge behavior with concurrent edits
- [ ] Test with network interruptions
### Persistence Changes
- [ ] Test database migrations if schema changed
- [ ] Verify data integrity across app restarts
- [ ] Check SQLite WAL mode behavior
- [ ] Test with large datasets
### UI Changes
- [ ] Test with debug UI enabled
- [ ] Verify on different screen sizes (iPad, desktop)
- [ ] Check touch and mouse input paths
- [ ] Test accessibility if UI changed
## Common Issues to Watch For
### Compilation
- Missing feature flags for conditional compilation
- Platform-specific code not properly gated with `#[cfg(...)]`
- Incorrect use of async/await in synchronous contexts
### Runtime
- Panics in production code (should return `Result` instead)
- Deadlocks with locks (use `parking_lot` correctly)
- Memory leaks with Arc/Rc cycles
- Thread spawning without proper cleanup
### iOS-Specific
- Using `println!` instead of `tracing` (doesn't work on iOS)
- Missing `tracing-oslog` initialization
- Incorrect bundle ID or entitlements
- Not testing on actual device for Pencil features
## When Task is Complete
1. **Run final validation**:
```bash
cargo fmt && cargo clippy && cargo test && cargo xtask ios-run
```
2. **Commit with good message**:
```bash
git add .
git commit -m "Clear, descriptive message"
```
3. **Push to remote**:
```bash
git push origin <branch-name>
```
4. **Create pull request** (if working in feature branch):
- Reference related issues
- Describe changes and rationale
- Note any breaking changes
- Request review if needed
5. **Update documentation**:
- Update RFCs if architectural change
- Update memory files if workflow changed
- Update README if user-facing change

46
.serena/memories/tech_stack.md Normal file
View File

@@ -0,0 +1,46 @@
# Tech Stack
## Language
- **Rust** (Edition 2021)
- Some Swift bridging code for iOS-specific features (Apple Pencil)
## Key Dependencies
### Networking & Synchronization
- **iroh** (v0.95) - P2P networking and NAT traversal
- **iroh-gossip** (v0.95) - Gossip protocol for message propagation
- **crdts** (v7.3) - Conflict-free Replicated Data Types
### Graphics & UI
- **Bevy** (v0.17) - Game engine for rendering and ECS architecture
- **egui** (v0.33) - Immediate mode GUI
- **wgpu** - Low-level GPU API
- **winit** (v0.30) - Window handling
### Storage & Persistence
- **rusqlite** (v0.37) - SQLite database bindings
- **serde** / **serde_json** - Serialization
- **bincode** - Binary serialization
### Async Runtime
- **tokio** (v1) - Async runtime with full features
- **futures-lite** (v2.0) - Lightweight futures utilities
### Utilities
- **anyhow** / **thiserror** - Error handling
- **tracing** / **tracing-subscriber** - Structured logging
- **uuid** - Unique identifiers
- **chrono** - Date/time handling
- **rand** (v0.8) - Random number generation
- **crossbeam-channel** - Multi-producer multi-consumer channels
### iOS-Specific
- **objc** (v0.2) - Objective-C runtime bindings
- **tracing-oslog** (v0.3) - iOS unified logging integration
- **raw-window-handle** (v0.6) - Platform window abstractions
### Development Tools
- **clap** - CLI argument parsing (in xtask)
- **criterion** - Benchmarking
- **proptest** - Property-based testing
- **tempfile** - Temporary file handling in tests

84
.serena/project.yml Normal file
View File

@@ -0,0 +1,84 @@
# list of languages for which language servers are started; choose from:
# al bash clojure cpp csharp csharp_omnisharp
# dart elixir elm erlang fortran go
# haskell java julia kotlin lua markdown
# nix perl php python python_jedi r
# rego ruby ruby_solargraph rust scala swift
# terraform typescript typescript_vts yaml zig
# Note:
# - For C, use cpp
# - For JavaScript, use typescript
# Special requirements:
# - csharp: Requires the presence of a .sln file in the project folder.
# When using multiple languages, the first language server that supports a given file will be used for that file.
# The first language is the default language and the respective language server will be used as a fallback.
# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
languages:
- rust
# the encoding used by text files in the project
# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
encoding: "utf-8"
# whether to use the project's gitignore file to ignore files
# Added on 2025-04-07
ignore_all_files_in_gitignore: true
# list of additional paths to ignore
# same syntax as gitignore, so you can use * and **
# Was previously called `ignored_dirs`, please update your config if you are using that.
# Added (renamed) on 2025-04-07
ignored_paths: []
# whether the project is in read-only mode
# If set to true, all editing tools will be disabled and attempts to use them will result in an error
# Added on 2025-04-18
read_only: false
# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
# Below is the complete list of tools for convenience.
# To make sure you have the latest list of tools, and to view their descriptions,
# execute `uv run scripts/print_tool_overview.py`.
#
# * `activate_project`: Activates a project by name.
# * `check_onboarding_performed`: Checks whether project onboarding was already performed.
# * `create_text_file`: Creates/overwrites a file in the project directory.
# * `delete_lines`: Deletes a range of lines within a file.
# * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
# * `execute_shell_command`: Executes a shell command.
# * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
# * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
# * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
# * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
# * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
# * `initial_instructions`: Gets the initial instructions for the current project.
# Should only be used in settings where the system prompt cannot be set,
# e.g. in clients you have no control over, like Claude Desktop.
# * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
# * `insert_at_line`: Inserts content at a given line in a file.
# * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
# * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
# * `list_memories`: Lists memories in Serena's project-specific memory store.
# * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
# * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
# * `read_file`: Reads a file within the project directory.
# * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
# * `remove_project`: Removes a project from the Serena configuration.
# * `replace_lines`: Replaces a range of lines within a file with new content.
# * `replace_symbol_body`: Replaces the full definition of a symbol.
# * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
# * `search_for_pattern`: Performs a search for a pattern in the project.
# * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
# * `switch_modes`: Activates modes by providing a list of their names
# * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
# * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
# * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
# * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
excluded_tools: []
# initial prompt for the project. It will always be given to the LLM upon activating the project
# (contrary to the memories, which are loaded on demand).
initial_prompt: ""
project_name: "aspen"
included_optional_tools: []