Discover before deciding
Repository discovery extracts project metadata, lock state, source imports, and stable fingerprints. The graph records explicit relationships between repositories, manifests, modules, packages, and resolved versions.
01 / THE IDEA
A closer look.
A local dependency-intelligence engine for Python repositories, implemented in Rust. Converge discovers manifests, lockfiles, and imports; constructs typed evidence; produces deterministic repair actions; validates a candidate in a temporary copy; and applies changes with snapshots and undo.
Dependency repair is a state transition, not just an install command. The interesting problem is preserving the relationship between evidence, a proposed edit, the exact candidate that passed validation, and the host files that are finally changed.
Explain a minimal repair
Diagnostics cite source locations and confidence. The planner creates typed AddDependency and lockfile actions for mapped missing dependencies, preserves existing version intent, and derives an ID from evidence and actions.
Validate away from the host
A temporary repository copy receives the candidate edits. Tool invocations use structured arguments, then uv generates or checks the lock and performs a frozen sync dry run according to the plan’s verification contract.
Apply with an escape route
The executor rechecks the fingerprint under a repository lock, snapshots affected files, uses atomic file replacement, and stores a receipt. Undo reads the recorded prior state rather than guessing an inverse patch.
02 / UNDER THE SURFACE
Evidence → plan → validated state
The host mutation boundary sits after isolated checks and a fresh fingerprint.
DRAG TO PAN · SELECT A NODE · + / − TO ZOOM
Read the architecture as text
- Explicit repository — Discovery begins from an explicit repository target. The snapshot captures source evidence, project metadata, lock state, and warnings rather than treating the process working directory as an implicit repair scope.
- Import evidence — Static import evidence is linked to the source module and location. Diagnosis maps recognized modules to distributions; uncertain or dynamic use cannot be inferred as complete coverage.
- Manifest / lock state — Declared normalized dependency names and parsed locked package names become separate evidence sets. Diagnosis compares them with mapped imports to distinguish missing declarations from lock drift.
- Typed evidence graph — build_graph produces stable nodes and edges using ordered maps. Repository, manifest, project, package, file, module, lockfile, and version entities retain the source fingerprint.
- Evidence diagnostics — Missing mapped dependencies, potentially unused declarations, and lock drift are emitted as stable diagnostics. Findings include evidence, severity, suggested actions, and whether they block environment creation.
- Deterministic plan — The current planner sorts and deduplicates missing distributions, adds declaration actions, and generates or refreshes a uv lockfile. With no deterministic repair it emits NoChange, not speculative source edits.
- Content-addressed ID — A BLAKE3 hasher combines the repository fingerprint, action IDs, and dependency ordering to form the plan ID. This ties the proposed transition to the evidence it was derived from.
- Temporary candidate — PreparedSandbox creates the candidate away from the target repository and applies planned file actions there. Its retained root becomes the validated source used by the later transaction.
- Structured uv checks — validate_prepared first executes any required lock action, then runs the plan’s verification checks through the typed tool adapter. All check results are collected into a VerificationReport.
- Validation contract — The report records plan ID, source fingerprint, network allowance, and individual results. Its passed flag is the conjunction of check outcomes and is validated before host mutation.
- Freshness gate — apply_validated_with_failure validates the report, canonicalizes the target, acquires a lock, rediscovers the repository, and refuses if its fingerprint differs from the plan’s snapshot.
- Recoverable snapshot — The transaction records whether each affected file existed and copies prior contents into .converge/snapshots. Metadata captures plan and environment state for receipts and recovery.
- Apply validated bytes — Candidate bytes are loaded from the validated root and written to target paths. If a file write or supported injected transaction phase fails, recorded originals are restored.
- Local persistence — The store crate persists derived graph state and append-only audit events locally. Repository source files remain the canonical evidence; the database is the query and audit layer.
- Undo receipt — undo_last uses the recorded snapshot and last-applied marker to recover prior files and any saved environment. Recovery is based on stored before-state rather than recomputing a reverse dependency plan.
03 / INTERACTIVE STUDY
Inspect the repair boundary
Model missing imports, how many have supported distribution mappings, and a repository edit after planning. Watch which actions are justified and when application must stop.
CHANGE THE INPUTS
Illustrative evidence accounting; “known mappings” summarizes coverage and is not a configurable source-code confidence threshold. No packages are installed or files changed.
ILLUSTRATIVE MODELLIVE
04 / ENGINEERING CHOICES
Why it works this way.
Evidence precedes action
Known import-to-distribution mappings justify declaration edits. An unused-dependency warning acknowledges dynamic or plugin use, so missing static imports alone do not justify silently deleting a dependency.
Separate checking from mutation
The temporary candidate, verification report, and live fingerprint form distinct boundaries. The executor can reject a stale plan even if its earlier sandbox checks passed.
Delegate resolution, own the transaction
uv remains the Python resolver and environment backend. Converge owns evidence, typed planning, isolated checks, host application, and recoverable snapshots around that resolver.
05 / OPEN THE SOURCE
Trace it back.
Implementation details, examples, and project documentation.
Deterministic planner
Cited diagnostics, ordered actions, plan hashing, and the concrete current repair scope.
Sandbox validation
Temporary candidate preparation and structured uv verification.
Transaction and undo
Report validation, stale fingerprint refusal, snapshots, replacement, and undo.
Typed graph
Explicit evidence nodes and deterministic edges.
Scope & limitations
- Static imports and curated mappings are incomplete evidence for dynamic imports or plugin loading. The current planner should not be read as a general solver for every Python environment failure.
- Atomic replacement applies to individual files; the transaction supplies snapshots and rollback around the sequence. This page has not rerun the repository’s failure-injection or environment tests.
Architecture and descriptions reflect the linked repository snapshot. The playground explains a mechanism; it does not execute the repository or report measured performance.