Documentationv1.4.0

Architecture

How gitresolve handles conflicts with mathematical precision and local determinism.

Core Principles

gitresolve is built on the principle of Local Determinism. Every resolution is produced by a fixed pipeline of rule-based engines that require zero network access and provide bit-identical results for the same input.

AST Integration

Instead of line diffs, we see syntax trees. This allows safe merging of unordered blocks like Go imports or Java annotations.

Rooted IO Sandbox

Mandatory os.Root sandboxing for all file operations (CWE-22 mitigation). IO is mathematically restricted to the repository root.

Pre-write Validation

No resolution is written to disk unless it passes the language parser. Syntax errors trigger immediate manual escalation.

Audit Persistence

Every decision is recorded in a namespaced log, making it possible to query 'why' every resolution occurred months later.

The Resolution Pipeline

A five-stage sequential processing engine.

01

Symmetric Marker Identification

Scanning for conflict markers with active brace-balance recovery. If markers are malformed or nested improperly, we escalate immediately.

02

Heuristic Classification

The engine categorizes the block: TypeIdentical, TypeWhitespace, TypeImport, TypeStructured, or TypeScalar.

03

Policy-Injected Routing

Active Policy Profiles (strict/aggressive) modify the confidence threshold required to proceed with automation.

04

Semantic Strategy Execution

Running the actual merge logic. For structured files, this is a deep recursive map merge. For code, it's an AST transformation.

05

Post-Resolution Syntax Gate

The final check. We run the native language compiler/parser on the 'merged' result. If valid, we write. If invalid, we roll back.

Engine Deep Dive

Visual breakdown of the deterministic resolution and history escalation engine.

Input Stage
Git Working Tree & Conflict Markers
Stage 1: Pre-Flight
Remote Divergence & Author Overlap Check
git log / git rev-list
Stage 2: AST Parsing
Syntax Tree & Cross-File Symbol Call Graph
go/parser & AST
Stage 3: History-Aware Risk Scoring Layer
Threshold Rules
Blast Radius
> 10 Callers
Co-Change
Strength ≥ 0.60
Import Cycles
Tarjan SCC
Author Weights
e^(-days/90)
Stage 4: Policy Gate
Policy Profile Routing & Syntax Verification Gate
policy.json
Auto-Resolution Path

Safe AST merge, post-write validation passed, bit-identical output written to disk.

Manual Escalation Path

2-line structural risk summary + parameter-templated suggested remediation command.

Permanent Audit Trail
SQLite: .gitresolve/audit.db (WAL mode)

Working Tree → Pre-Flight Divergence → AST Index → History Risk Scoring → Policy & Syntax Gates → Outcome

Structured Data Engine

For JSON, YAML, and TOML, gitresolve bypasses line-based text merging entirely. It parses both sides into memory, performs a 3-way recursive object merge including conservative array unioning, and re-serializes the result. This prevents common errors where merging two objects results in an invalid JSON comma or duplicated keys.