Metadata-Version: 2.4
Name: aetherflow-arch
Version: 0.1.0a1
Summary: Automated post-merge verification and dynamic conflict resolution in multi-agent programming environments
Author-email: Samir Baladi <gitdeeper@gmail.com>
Maintainer-email: Samir Baladi <gitdeeper@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/gitdeeper15/aetherflow
Project-URL: Documentation, https://github.com/gitdeeper15/aetherflow#readme
Project-URL: Repository, https://github.com/gitdeeper15/aetherflow
Project-URL: Bug Tracker, https://github.com/gitdeeper15/aetherflow/issues
Project-URL: Research Paper, https://doi.org/10.5281/zenodo.23979129
Project-URL: OSF Registration, https://doi.org/10.17605/OSF.IO/92Y3W
Project-URL: Release v2.0.0, https://github.com/gitdeeper15/aetherflow/releases/tag/v2.0.0
Project-URL: Official Site, https://aetherflow-site.netlify.app
Keywords: source control,merge queues,agentic software engineering,post-merge verification,auto-remediation,conflict resolution,distributed systems,formal methods
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: experiments
Requires-Dist: scikit-learn>=1.3; extra == "experiments"
Requires-Dist: matplotlib>=3.7; extra == "experiments"
Dynamic: license-file

# 📚 AetherFlow — Automated Post-Merge Verification and Dynamic Conflict Resolution in Multi-Agent Programming Environments

### A Formal Architecture for Lock-Free Integration and Proactive Remediation at Agent Scale

---

<!-- Core -->
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23979129.svg)](https://doi.org/10.5281/zenodo.23979129)
[![License: MIT + CC-BY-4.0](https://img.shields.io/badge/License-MIT%20%2B%20CC--BY--4.0-crimson.svg)](LICENSE)
[![ORCID](https://img.shields.io/badge/ORCID-0009--0003--8903--0029-a6ce39)](https://orcid.org/0009-0003-8903-0029)

<!-- PyPI -->
[![PyPI version](https://img.shields.io/pypi/v/aetherflow?color=gold&label=PyPI)](https://pypi.org/project/aetherflow/)
[![PyPI downloads](https://img.shields.io/pypi/dm/aetherflow?color=gold&label=Downloads)](https://pypi.org/project/aetherflow/)
[![PyPI status](https://img.shields.io/pypi/status/aetherflow?color=gold)](https://pypi.org/project/aetherflow/)

<!-- OSF -->
[![OSF Preregistration](https://img.shields.io/badge/OSF-Preregistration-blueviolet)](https://doi.org/10.17605/OSF.IO/92Y3W)
[![OSF Project](https://img.shields.io/badge/OSF-Project-blueviolet)](https://osf.io/92y3w)
[![Registration DOI](https://img.shields.io/badge/Reg.%20DOI-10.17605%2FOSF.IO%2F92Y3W-blue)](https://doi.org/10.17605/OSF.IO/92Y3W)
[![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)

<!-- Stack -->
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://python.org)

<!-- Website -->
[![Website](https://img.shields.io/badge/Website-aetherflow--site.netlify.app-success)](https://aetherflow-site.netlify.app)

<!-- Release -->
[![Record ID](https://img.shields.io/badge/Record%20ID-AETHERFLOW--01-informational)](https://doi.org/10.5281/zenodo.23979129)
[![Zenodo](https://img.shields.io/badge/Zenodo-Published-blue)](https://doi.org/10.5281/zenodo.23979129)
[![GitHub Release](https://img.shields.io/badge/Release-v2.0.0-green)](https://github.com/gitdeeper15/aetherflow/releases/tag/v2.0.0)

---

> ⚠️ **Status: v2.0.0 — Empirical Implementation.**
>
> Reference implementation built and tested (24 tests, 98% coverage).
> 5 experiments executed. No real-world deployment evaluated.
> All empirical results are preliminary. See `REPORTS/v2.0.0/report.md`
> and Section 9 (Limitations) of the manuscript.

---

> *"Scaling code integration for autonomous AI agents requires abandoning traditional pre-merge gating models."*
>
> — AetherFlow, Conclusion

> *"Auto-remediation is not an exception handler; it is the primary integration mechanism."*

---

## Table of Contents

- [Overview](#overview)
- [The Central Question](#the-central-question)
- [Formal Definitions](#formal-definitions)
- [Propositions](#propositions)
- [Architectural Pillars](#architectural-pillars)
- [Empirical Results (v2.0.0)](#empirical-results-v200)
- [Relation to AetherGit](#relation-to-aethergit)
- [Platforms & Mirrors](#platforms--mirrors)
- [Installation](#installation)
- [Project Structure](#project-structure)
- [Version History](#version-history)
- [Citation](#citation)
- [Author](#author)
- [License](#license)

---

## Overview

**AetherFlow** is a formal architecture that replaces traditional merge queues
with lock-free direct entry, backed by probabilistic post-merge verification
and proactive auto-remediation agents. By decoupling validation from code
admission, AetherFlow **structurally eliminates** queue starvation and is
**designed** to reduce integration latency by over an order of magnitude.

The program is specified through **three mathematically rigorous constructs**:

| # | Construct | Version | Status |
|---|---|---|---|
| 1 | **Dynamic Conflict Window** | 1.0.0 | ✅ Defined |
| 2 | **Post-Merge Verification Operator** | 1.0.0 | ✅ Defined |
| 3 | **Auto-Remediation Bound** | 1.0.0 | ✅ Defined |

In **v2.0.0**, all three are implemented as Python modules with tests and
experiments. The package is available on **PyPI** as `aetherflow`.

<p align="center">
  <img src="figures/fig1_conflict_window.png" 
       alt="AetherFlow — Dynamic Conflict Window" 
       width="100%">
</p>

<p align="center">
  <em>Figure 1 — The dynamic conflict window W(cᵢ, cⱼ) = 1 − exp(−κ·O·e^(−τ/θ)) as a function of temporal distance for three overlap levels.</em>
</p>

---

## The Central Question

> **What architectural and formal changes become necessary — and which remain
> optional design choices — when merge queues must be replaced by post-merge
> verification and auto-remediation in multi-agent programming environments?**

This question is **structural**, not accusatory or normative. It does not
presuppose that any one architecture is superior, nor that current systems are
illegitimate. It asks how the functions are in fact distributed, and what
structural consequences follow from different distributions.

---

## Formal Definitions

*Status: Defined, version 1.0.0.*

### Definition 1 — Dynamic Conflict Window

```

W(cᵢ, cⱼ) = 1 − exp(−κ·O·e^(−τ/θ))

```

Where:
- `τ(cᵢ, cⱼ)` = temporal distance between changeset injections
- `O ∈ [0, 1]` = overlap score from file-footprint overlap and dependency-graph proximity
- `κ > 0` = sensitivity
- `θ > 0` = decay horizon

### Definition 2 — Post-Merge Verification Operator

```

V(c) = ⊕_V(δ_i, {V(p) | p ∈ P(c_i)}, CI(c_i))

```

Three-valued: **verified**, **failed**, or **tainted**.

<p align="center">
  <img src="figures/fig2_verification_operator.png" 
       alt="AetherFlow — Post-Merge Verification Operator" 
       width="100%">
</p>

<p align="center">
  <em>Figure 2 — Recursive verification over a changeset DAG. c2 fails on a check attributable to its own delta; its descendants c4 and c5 are tainted, not failed; c3 is unaffected.</em>
</p>

### Definition 3 — Auto-Remediation Bound

```

P(Remediation) ≥ 1 − (λ_fail/μ_remediate)^K · e^(−γ·T_react)

```

Where:
- `λ_fail` = rate of post-merge integration failures
- `μ_remediate` = aggregate processing capacity of remediation agents
- `K` = remediation capacity tier depth
- `T_react` = remediation time budget
- `γ` = decay coefficient on residual risk per unit of that budget

<p align="center">
  <img src="figures/fig3_remediation_bound.png" 
       alt="AetherFlow — Auto-Remediation Bound" 
       width="100%">
</p>

<p align="center">
  <em>Figure 3 — The Equation 3 lower bound versus tier depth K for three remediation time budgets, with ρ = 0.6 and γ = 0.15 (illustrative parameters).</em>
</p>

---

## Propositions

### Proposition 1 — Admission Independence

Under lock-free entry, the time from submission to admission to the trunk log
is `a` (an atomic append with cost `O(|δ|)`), **independent of the CI duration
`s` and of the verification backlog**.

### Proposition 2 — Monotonicity of Conflict Window

Under Equation 1a, `W` is **strictly decreasing in `τ` for `O > 0`**, and
**strictly increasing in `O` for finite `τ`**.

### Proposition 3 — Minimum Tier Depth

If `ρ < 1`, the right-hand side of Equation 3 is non-decreasing in `K` and in
`T_react`, and tends to 1 as `K` grows without bound. For a target residual
risk `ε ∈ (0, 1)`, the bound is at least `1 − ε` whenever:

```

K ≥ (ln(1/ε) − γ·T_react) / ln(1/ρ)

```

---

## Architectural Pillars

*Status: Specified, version 1.0.0.*

### Pillar 1 — Lock-Free Merge Entry

Every incoming agentic changeset is appended to the trunk's reference log by
an atomic compare-and-swap on the log head, retried on contention. No queue,
branch-protection gate, or global lock stands between submission and admission.

### Pillar 2 — Post-Merge Verification Layer

Immediately after admission, verification workers execute builds, tests, and
semantic dependency scans against the new state. Work is scheduled in priority
order based on conflict-window scores and dependency out-degree.

### Pillar 3 — Proactive Remediation Agents

When a changeset is marked failed, a remediation agent is dispatched with the
failing changeset, the failing checks, and the last verified state. The policy
is graded, with four tiers of compensation plus a final escalation to a human owner.

<p align="center">
  <img src="figures/fig4_architecture.png" 
       alt="AetherFlow — Three Architectural Pillars" 
       width="100%">
</p>

<p align="center">
  <em>Figure 4 — The three architectural pillars: (1) Lock-Free Merge Entry; (2) Post-Merge Verification Layer; (3) Proactive Remediation Agents.</em>
</p>

### Verified-Head Discipline

The principal risk of lock-free entry is that the trunk head may be temporarily
unverified. AetherFlow confines that risk by distinguishing two references:

- **Admission head** — advances on every append.
- **Verified head** — the most recent changeset all of whose ancestors are verified.

Consumers (releases, deployments, downstream) read the verified head; producers
branch from the admission head.

---

## Empirical Results (v2.0.0)

| # | Experiment | Result |
|---|------------|--------|
| 1 | Conflict Window (Eq. 1a) | κ = 2.892, θ = 4.000, AUC = 0.894 |
| 2 | Remediation Bound (Eq. 3) | K = 8 → P(Remediation) ≥ 1.0000 |
| 3 | Attribution Accuracy | F1 = 1.000 (with mitigation) |
| 4 | Guardrail Effectiveness | 100% block rate (192/192) |
| 5 | Scheduler Simulation | 2.5× speedup vs FIFO |

> **Status note:** Experiment 1 uses synthetic data (self-consistency test).
> Experiments 2–5 use simulated logs. No real-world deployment evaluated.
> See `REPORTS/v2.0.0/report.md` for full details.

---

## Relation to AetherGit

**AetherGit** — a high-throughput, always-online version control framework for
agentic software engineering. Examined as a **complementary system**:

- **AetherGit** = storage layer (lock-free changesets, tiered cache, DAG)
- **AetherFlow** = integration layer (lock-free entry, post-merge verification, remediation)

The two systems are **methodologically independent**. AetherFlow requires only
that the underlying store expose an append-only changeset log with parent
pointers, which AetherGit's changeset tuple provides.

- AetherGit DOI: https://doi.org/10.5281/zenodo.23966896
- Prior work DOI: https://doi.org/10.5281/zenodo.23934465

---

## Platforms & Mirrors

| Platform | URL | Role | Status |
|---|---|---|---|
| **GitHub** | https://github.com/gitdeeper15/aetherflow | Source code, issues, PRs | ✅ Active |
| **GitLab** | https://gitlab.com/gitdeeper15/aetherflow | Mirror repository | ✅ Active |
| **Codeberg** | https://codeberg.org/gitdeeper15/aetherflow | Mirror repository | ✅ Active |
| **Bitbucket** | https://bitbucket.org/gitdeeper15/aetherflow | Mirror repository | ✅ Active |
| **PyPI** | https://pypi.org/project/aetherflow/ | Python package | ✅ **Published** |
| **Zenodo** | https://doi.org/10.5281/zenodo.23979129 | Citable DOI, paper archive | ✅ Published |
| **OSF** | https://doi.org/10.17605/OSF.IO/92Y3W | Registration | ✅ Published |
| **Website** | https://aetherflow-site.netlify.app | Live documentation | ✅ Active |
| **ORCID** | https://orcid.org/0009-0003-8903-0029 | Author identity | ✅ Active |

---

## Installation

```bash
pip install aetherflow
```

Quick start

```python
from aetherflow import (
    conflict_window,
    remediation_bound,
    minimum_tier_depth,
)

# Definition 1: dynamic conflict window
w = conflict_window(tau=1.0, overlap=0.5)

# Definition 3: auto-remediation bound
p = remediation_bound(lambda_fail=0.6, mu_remediate=1.0, K=8, gamma=0.15, T_react=8.0)

# Proposition 3: minimum tier depth
K = minimum_tier_depth(epsilon=0.008, rho=0.6, gamma=0.15, T_react=8.0)
```

CLI

```bash
aetherflow conflict-window --tau 1.0 --overlap 0.5
aetherflow remediation-bound --lambda-fail 0.6 --mu-remediate 1.0 --K 8
aetherflow min-tier-depth --epsilon 0.008 --rho 0.6
```

---

Project Structure

```
AetherFlow/
├── src/aetherflow/                # Reference implementation
│   ├── admission/                 # Pillar 1
│   ├── verification/              # Pillar 2
│   ├── remediation/               # Pillar 3
│   ├── conflict/                  # Definition 1
│   ├── models.py
│   └── cli.py
├── tests/                         # 24 tests, 98% coverage
├── experiments/                   # 5 protocols
├── docs/
│   ├── 01_formalization/          # Definitions 1-3
│   ├── 02_architecture/           # Pillars
│   ├── 03_conflict_window/
│   ├── 04_evaluation/
│   └── 05_implementation/         # v2.0.0
├── figures/
├── PUBLICATION/
│   ├── AetherFlow_Research_Paper.pdf
│   └── Netlify/
├── REPORTS/
│   └── v2.0.0/
│       └── report.md
├── CHANGELOG.md
├── CITATION.cff
├── INVENTORY.md
├── LICENSE
├── PROJECT_SUMMARY.txt
├── README.md
├── VERSION
└── pyproject.toml
```

---

Version History

Version Release Focus Status
v2.0.0 2026-11 (release) Empirical implementation + 5 experiments ✅ Implemented
v1.0.0 2026-11 (release) Formalization (3 definitions, 3 propositions) ✅ Defined
(planned) 2027+ Real-world deployment + benchmarking Not executed

v2.0.0: Reference implementation with 24 tests (98% coverage) and 5 experiments.
Results are preliminary; see REPORTS/v2.0.0/report.md for details.

---

Citation

Primary Manuscript (AetherFlow v1.0.0)

```bibtex
@techreport{baladi2026aetherflow,
  author       = {Baladi, Samir},
  title        = {AetherFlow: Automated Post-Merge Verification and Dynamic Conflict Resolution in Multi-Agent Programming Environments},
  institution  = {Ronin Institute / Rite of Renaissance},
  type         = {Research Paper},
  year         = {2026},
  month        = {November},
  version      = {1.0.0},
  doi          = {10.5281/zenodo.23979129},
  url          = {https://doi.org/10.5281/zenodo.23979129},
  note         = {Initial Program Manuscript --- Formalization Stage.}
}
```

Software Archive (PyPI + Zenodo)

```bibtex
@software{baladi2026aetherflow_v2,
  author       = {Baladi, Samir},
  title        = {{AetherFlow} v2.0.0: Empirical Implementation of Automated Post-Merge Verification and Dynamic Conflict Resolution},
  year         = {2026},
  month        = {November},
  publisher    = {PyPI},
  version      = {2.0.0},
  doi          = {10.5281/zenodo.23979129},
  url          = {https://pypi.org/project/aetherflow/},
  note         = {Reference implementation.
                  Available via pip install aetherflow.}
}
```

---

Author

Samir Baladi
 Interdisciplinary AI Researcher — Ronin Institute / Rite of Renaissance

· Research Area: Computer Science / Software Engineering
· Research Domain: Version Control Systems, Distributed Systems, Agentic Software Engineering
· Research Type: Formal Architecture Proposal — Conceptual and Structural Analysis
· 📧 Email: gitdeeper@gmail.com
· 🔗 ORCID: https://orcid.org/0009-0003-8903-0029
· 🐙 GitHub: https://github.com/gitdeeper15/aetherflow
· 🦊 GitLab: https://gitlab.com/gitdeeper15/aetherflow
· 🟦 Codeberg: https://codeberg.org/gitdeeper15/aetherflow
· 🪣 Bitbucket: https://bitbucket.org/gitdeeper15/aetherflow
· 🐝 PyPI: https://pypi.org/project/aetherflow/
· 🌐 Official Site: https://aetherflow-site.netlify.app

---

License

```
MIT License (code)
Copyright © 2026 Samir Baladi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

---

Documentation, manuscript, and figures: CC-BY-4.0
Full license text: https://creativecommons.org/licenses/by/4.0/legalcode
```

---

AetherFlow — Initial Program Manuscript v2.0.0
© 2026 Samir Baladi — Ronin Institute / Rite of Renaissance — MIT (code) + CC-BY-4.0 (docs)
Zenodo: https://doi.org/10.5281/zenodo.23979129
OSF: https://doi.org/10.17605/OSF.IO/92Y3W
PyPI: https://pypi.org/project/aetherflow/
Official Site: https://aetherflow-site.netlify.app
