Home / Docs

Suture Production Roadmap

Version: 5.4.0 Date: 2026-05-15 Status: Post-audit -- all 12 phases complete, CI green, ready for production push

1. Audit Summary (2026-05-15)

1.1 Test Results

MetricValue Total tests1,759 passed, 0 failed, 20 ignored Crates tested41 (excluding fuzz, py, node) Clippy warnings0 (workspace-wide, -D warnings) Format checkClean (cargo fmt --all -- --check) Determinism tests7/7 passed (BLAKE3, patch ID, commit, merge, push/pull, diff symmetry, branch idempotent) Property-based tests21 proptest suites, 10K+ cases

1.2 CI/CD Status

WorkflowStatusNotes CI (lint + test matrix)GREEN16/17 jobs pass; 1 flaky macOS runner (transient rustup issue) SecurityGREENcargo-audit clean, clippy clean, SBOM generated Docker BuildGREENMulti-stage build fixed, produces suture-platform image ReleaseREADY4-platform binary matrix (Linux x86_64, macOS x86_64+aarch64, Windows) PagesDEPLOYEDdocs-site/ live at suture.dev CoverageGENERATEDllvm-cov report uploaded as artifact

1.3 CI Fixes Applied (This Session)

  1. test-cli protoc: Added protoc installation to all 3 OS matrices in test-cli job
  2. build-release protoc: Added protobuf-compiler to system dependencies
  3. MockBackend trait: Added missing backend_name() method to BlobBackend impl in S3 feature test
  4. Dockerfile: Converted from broken single-stage (expected pre-built binary) to proper multi-stage Rust build
  5. Documentation: Removed emoji from ROADMAP.md, updated test counts to match actual (1,759), fixed stale LFS doc comments

1.4 Code Quality

CheckResult todo!() calls0 unimplemented!() calls0 (1 in test fixture string, not production) FIXME/HACK/XXX comments0 Stubs (incomplete features)2 (WASM plugin diff() and format_diff() -- feature-gated, documented) Empty function bodies5 (2 FUSE destroy -- standard pattern; 3 plugin-sdk conditional compilation stubs) Stale doc comments2 fixed (LFS Push/Pull "not yet implemented") Unsafe blocks33 (all with SAFETY comments per prior audit)

1.5 Documentation Audit

CheckResult Emojis in markdownRemoved from ROADMAP.md (was only file with emojis) Test counts accurateUpdated: 1,759 (was 1,747); suture-e2e 200 (was 226) Stale version referencesFixed Mathematical correctnessPerformance baselines have quantitative thresholds, all verified Website (docs-site)Live at suture.dev, interactive demo functional Detailed docs (docs/)77 HTML+MD files exist locally; NOT deployed to GitHub Pages (only docs-site is)

1.6 Known Issues (Non-Blocking)

IssueSeverityResolution macOS CI test-cli flakyLowTransient runner issue; re-run passes docs/ not deployed to websiteMediumOnly docs-site/ deployed; need unified docs build suture-py excluded from workspaceMediumPyO3 build complexity; needs separate CI matrix desktop-app excluded from workspaceLowTauri v2 dependency conflicts CWD mutex in CLI testsMediumForces --test-threads=1; refactor to tempdir per test WASM plugin diff/format_diff stubsLowFeature-gated; acceptable for experimental feature

2. Path to Production

Phase P0: Documentation Deployment (1 week)

Deploy all docs/ content to the website so users can access quickstart, API reference, architecture, and performance docs online.

TaskEffortPriority Build docs/ HTML files into docs-site/ or deploy docs/ as subpath2dCritical Update CNAME from suture.dev if needed0.5dHigh Add navigation between docs-site landing and docs/ pages1dHigh Verify all internal links work on deployed site1dHigh Add version selector for docs (current vs. previous)1dMedium

Phase P1: CI Reliability (1 week)

Eliminate flaky CI and reduce pipeline time.

TaskEffortPriority Add retry logic for flaky macOS jobs0.5dHigh Cache protoc binary instead of apt-get install0.5dMedium Parallelize cargo check and cargo clippy0.5dMedium Add --test-threads=4 to test-cli (refactor CWD mutex)3dHigh Add merge queue for main branch protection1dMedium Update actions/checkout to v5 (Node 24 compatibility)0.5dHigh

Phase P2: Soundness Hardening (2 weeks)

Eliminate all remaining soundness concerns.

TaskEffortPriority Audit all 33 unsafe blocks with formal SAFETY comments3dCritical FUSE Send/Sync: document libfuse3 threading guarantees2dCritical SHM: add #[repr(C)] to shared memory structs0.5dCritical Binary drivers: add debug_assert!(from_utf8().is_ok()) before from_utf8_unchecked1dCritical Remove CWD mutex from CLI tests (refactor to tempdir)3dHigh Add cargo semver-checks to CI for API stability1dHigh

Phase P3: Test Coverage (2 weeks)

Establish quantitative coverage baselines and enforce thresholds.

TaskEffortPriority Set coverage threshold in CI (>80% line, >70% branch)1dHigh Add missing tests for connector crates (Airtable, Sheets, Notion)3dMedium Add integration tests for desktop-app3dMedium Add WASM plugin E2E test with real .wasm file2dMedium Property-based tests for merge engine (expand from 21 suites)2dHigh

Phase P4: Performance at Scale (3 weeks)

Optimize for enterprise-scale repositories.

TaskEffortPriority Parallel file hashing with rayon for suture add .2dHigh Incremental file tree computation in commit1dHigh Lazy patch deserialization in suture log2dHigh Pack files for small blob deduplication5dMedium Partial clone / sparse checkout5dMedium Criterion benchmarks in CI with 10% regression gating2dHigh Background GC with configurable thresholds3dMedium

Phase P5: suture-merge Library v1.0 (2 weeks)

Stabilize the standalone merge library for ecosystem adoption.

TaskEffortPriority Add merge_sql(), merge_ical(), merge_feed() to public API2dHigh Stabilize API surface, document stability guarantees2dCritical Add conflict callback API for programmatic resolution2dHigh Publish all 37 crates to crates.io in dependency order1dHigh Add semver-checks to CI1dCritical Write migration guide (v0.x to v1.0)1dMedium

Phase P6: Enterprise Features (4 weeks)

Features required for enterprise deployment.

TaskEffortPriority Backup/restore tooling for hub3dHigh Prometheus metrics endpoint (/metrics)2dHigh Per-user rate limiting2dMedium API versioning (/api/v1/ prefix)2dHigh OAuth2 scope-based tokens + refresh rotation3dMedium Per-repo permissions (owner/collaborator/reader)3dHigh Branch protection rules2dHigh Audit logging for all permission changes2dHigh Structured JSON logging with tracing-subscriber1dHigh OpenTelemetry distributed tracing3dMedium

Phase P7: Advanced Merge (3 weeks)

Expand semantic merge to harder cases.

TaskEffortPriority DOCX track-changes-aware merge5dHigh XLSX formula-aware merge (AST-level)5dHigh PPTX animation/timing preservation3dMedium OOXML comment/annotation merge2dMedium Lockfile merge (Cargo.lock, package-lock.json)3dHigh Custom merge strategies via WASM plugins3dMedium

Phase P8: Desktop App (4 weeks)

Complete the Tauri desktop application.

TaskEffortPriority Fix Tauri build in workspace (resolve dependency conflicts)3dCritical Add CI matrix (macOS + Windows + Linux)2dHigh Real-time sync status in UI3dHigh Visual merge conflict resolution (side-by-side editor)5dHigh Repository browser with history sidebar3dMedium System tray notifications1dMedium Smoke tests for basic workflows2dHigh

Phase P9: Editor Integration Polish (3 weeks)

Deepen editor plugin integrations.

TaskEffortPriority VS Code: real-time semantic diff preview3dHigh JetBrains: merge conflict resolution UI5dMedium Neovim: stable release to MELPA/lazy.nvim1dMedium LSP: add code action for conflict resolution2dMedium

Phase P10: Ecosystem Growth (3 weeks)

Expand distribution channels.

TaskEffortPriority suture-py: re-include in CI, publish to PyPI3dMedium Homebrew formula update to latest version0.5dHigh AUR PKGBUILD update0.5dHigh Nix flake update0.5dMedium Docker multi-arch image (amd64 + arm64)2dHigh Install script verification on Ubuntu, macOS, Fedora, Arch1dHigh

Phase P11: WASM Plugin Ecosystem (3 weeks)

Enable user-extensible merge drivers.

TaskEffortPriority Implement WASM plugin diff() and format_diff()5dHigh Publish suture-plugin-sdk to crates.io1dHigh Plugin documentation and tutorial2dHigh Example plugins (INI, protobuf, dotenv)3dMedium Plugin signing and marketplace registry5dLow Fuel metering and memory limits enforcement2dMedium

Phase P12: v1.0 Release (2 weeks)

Ship a stable, documented, well-supported v1.0.

TaskEffortPriority API stability audit (cargo-semver-checks)2dCritical Breaking change detection in CI1dCritical Compatibility testing: Rust 1.75+, Ubuntu 22.04+, macOS 13+, Windows 10+3dHigh Migration guide (v0.x to v1.0)2dHigh Troubleshooting guide2dMedium Video tutorials (3-5 minute walkthroughs)5dMedium GPG signing for release binaries1dHigh Automated release workflow with SHA256 checksums1dHigh All ADRs published2dMedium

3. Timeline

PhaseFocusTarget VersionDurationStart P0Documentation deploymentv5.4.11 week2026-05-15 P1CI reliabilityv5.4.21 week2026-05-22 P2Soundness hardeningv5.5.02 weeks2026-05-29 P3Test coveragev5.6.02 weeks2026-06-12 P4Performance at scalev6.0.03 weeks2026-06-26 P5suture-merge v1.0v6.1.02 weeks2026-07-17 P6Enterprise featuresv7.0.04 weeks2026-07-31 P7Advanced mergev7.1.03 weeks2026-08-28 P8Desktop appv8.0.04 weeks2026-09-18 P9Editor integrationsv8.1.03 weeks2026-10-16 P10Ecosystem growthv8.2.03 weeks2026-11-06 P11WASM pluginsv9.0.03 weeks2026-11-27 P12v1.0 releasev10.0.02 weeks2026-12-18

Estimated total: 33 weeks (approximately 8 months to v1.0)

4. Metrics Targets

Metricv5.4.0 (now)v6.0v8.0v10.0 Tests1,7591,9002,2002,500 Branch coverage (critical)Unknown>80%>90%>95% Lean 4 proofs16162432 Semantic drivers17202428 crates.io crates37374042 CLI commands58606570 Unsafe blocks33252015 Unsafe blocks with SAFETY33333333 Clippy warnings0000 CI pipeline time~15m<10m<12m<12m suture-merge downloads/moTBD1K5K20K Website pages1 (landing)30+50+50+

5. Risk Register

RiskProbabilityImpactMitigation Rust edition upgrade breaks compilationMediumHighPin rust-toolchain.toml, test with nightly SQLite WAL corruption on crashLowCriticalWAL checkpoint on shutdown, fsck on startup BLAKE3 collision (theoretical)NegligibleCriticalMonitor research, plan migration Raft split-brainLowCriticalPersist election state, BTreeMap ordering WASM sandbox escapeLowCriticalLimit host imports, review wasmtime advisories Supply chain attack via dependencyMediumHighcargo audit in CI, lockfile pinning, entropy analysis Driver regressionMediumHighProperty-based tests, E2E lifecycle tests Performance regressionMediumMediumCriterion in CI with regression gating Tauri breaking changesMediumMediumPin Tauri version, test before upgrade crates.io publish failureLowLowDry-run in CI, manual review before publish

6. Strategic Decisions

What NOT to Do

DecisionRationale Do not migrate to PostgreSQLSQLite + Raft covers single-node and distributed Do not implement QUICTCP + Zstd achieves adequate latency Do not implement NFSv4/SMB3FUSE3 + WebDAV covers primary use cases Do not migrate to FlatBuffersbincode + Zstd is performant and well-tested Do not optimize for nanosecond latencyVCS operations are I/O bound

What to Double Down On

DecisionRationale Semantic merge qualitySole differentiator from Git suture-merge library adoptionGrowth vector; low friction (cargo add) Formal verificationUnique in VCS space; builds trust for regulated industries Performance at scaleEnterprise adoption requires 100K+ files Editor integrationsWhere users spend their time

7. Current Technical Debt

IDSeverityDescriptionTarget Phase TD-1CriticalCLI CWD mutex forces --test-threads=1 in CIP1 TD-2CriticalFUSE unsafe impl Send/Sync soundness documentationP2 TD-3CriticalSHM unsafe impl Send/Sync -- no repr(C) proofP2 TD-4Criticalfrom_utf8_unchecked in 8+ binary drivers -- needs debug-assertP2 TD-5Highsuture-py excluded from workspace/CIP10 TD-6Highdesktop-app excluded from workspace/CIP8 TD-7HighNo MSRV policy or rust-toolchain.toml pinP1 TD-8High33 unsafe blocks need formal SAFETY auditP2 TD-9MediumCode coverage measured but no threshold enforcementP3 TD-10MediumNo performance regression gating in CIP4 TD-11Mediumdocs/ content not deployed to websiteP0 TD-12Low5 E2E tests ignored (FUSE needs root)P2 TD-13LowWASM plugin diff/format_diff stubsP11
GitHub · AGPL-3.0