agentdescent 0.1.0__py3-none-any.whl

agentdescent/__init__.py

@@ -0,0 +1,169 @@
+"""AgentDescent: a parallel, self-evolving framework for accelerating RSI.
+
+A systematic port of the parallel-training playbook (data/tensor/pipeline
+parallelism, parameter servers, decoupled/async RL, partial rollout) onto
+recursive self-improvement, where the "parameters" are a library of evolvable
+artifacts (skills, prompts, harness modules, verifiers) and the "gradients" are
+diffs carrying evidence cards.
+
+See ``agentdescent_design.md`` for the full design; each module cites the section
+it implements.
+"""
+
+from .evolvable import (
+    Contract,
+    Diff,
+    EvidenceCard,
+    Evolvable,
+    VersionVector,
+    vv_dominates,
+    vv_staleness,
+)
+from .ledger import Ledger, Snapshot, CASConflict, ContractRejected
+from .verifier import ThreeLayerVerifier, VerifierBudget
+from .scheduler import (
+    AuditScheduler,
+    DurationEstimator,
+    ResumeQueue,
+    TaskCluster,
+    TaskScheduler,
+    fifo_makespan,
+    lpt_schedule,
+)
+from .governance import Layer, classify, assert_mutable, GovernanceError, L1SerialGate
+from .aggregator import (
+    Aggregator,
+    AggregatorConfig,
+    AggregatorProtocol,
+    AggregatorFactory,
+    MergeReport,
+    EvidenceBuffer,
+)
+from .staleness import (
+    StaleAction,
+    StalenessPolicy,
+    FullStaleness,
+    GuardedStaleness,
+    ReflectiveStaleness,
+    get_policy,
+)
+from .worker import Worker
+from .orchestrator import AgentDescent, RoundStat, run_fork_baseline
+from .agents import (
+    Completion,
+    claude,
+    echo,
+    from_callable,
+    openai_compatible,
+    with_retries,
+)
+from .evolution import (
+    Agent,
+    LLMAgent,
+    Task,
+    EvolvingArtifact,
+    Strategy,
+    AppendRules,
+    KeyedRules,
+    EvolutionResult,
+    RoundInfo,
+    evolve,
+    claude_agent,
+    rule_id,
+)
+from .async_evolve import async_evolve
+from .async_runtime import AsyncAgentDescent, AsyncConfig, AsyncStats
+from .parallel import (
+    ParallelMode,
+    ParallelStrategy,
+    WorkUnit,
+    DataParallel,
+    TensorParallel,
+    PipelineParallel,
+    TensorParallelMerge,
+    PipelineChain,
+    SectionViolation,
+    assign_sections,
+    section_of,
+    shard_round_robin,
+)
+
+__version__ = "0.7.0"
+
+__all__ = [
+    "Contract",
+    "Diff",
+    "EvidenceCard",
+    "Evolvable",
+    "VersionVector",
+    "vv_dominates",
+    "vv_staleness",
+    "Ledger",
+    "Snapshot",
+    "CASConflict",
+    "ContractRejected",
+    "ThreeLayerVerifier",
+    "VerifierBudget",
+    "AuditScheduler",
+    "ResumeQueue",
+    "DurationEstimator",
+    "lpt_schedule",
+    "fifo_makespan",
+    "TaskCluster",
+    "TaskScheduler",
+    "Layer",
+    "classify",
+    "assert_mutable",
+    "GovernanceError",
+    "L1SerialGate",
+    "Aggregator",
+    "AggregatorConfig",
+    "AggregatorProtocol",
+    "AggregatorFactory",
+    "MergeReport",
+    "EvidenceBuffer",
+    "StaleAction",
+    "StalenessPolicy",
+    "FullStaleness",
+    "GuardedStaleness",
+    "ReflectiveStaleness",
+    "get_policy",
+    "Worker",
+    "AgentDescent",
+    "RoundStat",
+    "run_fork_baseline",
+    "AsyncAgentDescent",
+    "AsyncConfig",
+    "AsyncStats",
+    "ParallelMode",
+    "ParallelStrategy",
+    "WorkUnit",
+    "DataParallel",
+    "TensorParallel",
+    "PipelineParallel",
+    "TensorParallelMerge",
+    "PipelineChain",
+    "SectionViolation",
+    "assign_sections",
+    "section_of",
+    "shard_round_robin",
+    "Completion",
+    "claude",
+    "echo",
+    "from_callable",
+    "openai_compatible",
+    "with_retries",
+    "Agent",
+    "LLMAgent",
+    "Task",
+    "EvolvingArtifact",
+    "Strategy",
+    "AppendRules",
+    "KeyedRules",
+    "EvolutionResult",
+    "RoundInfo",
+    "evolve",
+    "async_evolve",
+    "claude_agent",
+    "rule_id",
+]

agentdescent/agents.py

@@ -0,0 +1,112 @@
+"""Provider-agnostic inference -- connect any agent or LLM to the framework.
+
+This is the general "talk to a model/agent" layer. It is deliberately kept
+**out of** :mod:`agentdescent.evolution`: skill evolution is just *one* application
+built on the framework, and how you reach a model has nothing to do with it.
+
+The whole contract is one type:
+
+    Completion = Callable[[str], str]      # prompt -> text
+
+Anything that maps a prompt to text is a completion -- an LLM call, a
+tool-using agent loop, a canned stub for tests. The adapters below build
+completions for Claude, an arbitrary callable, or a deterministic echo, and
+:func:`with_retries` wraps any of them with backoff. Higher layers
+(the evolution engine's LLMAgent, or your own) turn a completion
+into whatever task interface they need.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.request
+from typing import Callable, Optional
+
+Completion = Callable[[str], str]
+
+
+def from_callable(fn: Completion) -> Completion:
+    """Identity adapter -- documents that any ``prompt -> text`` callable works."""
+    return fn
+
+
+def echo(transform: Optional[Callable[[str], str]] = None) -> Completion:
+    """A deterministic, no-network completion for tests and dry runs.
+
+    Returns the prompt unchanged, or ``transform(prompt)`` if given."""
+    def complete(prompt: str) -> str:
+        return transform(prompt) if transform else prompt
+    return complete
+
+
+def with_retries(completion: Completion, attempts: int = 3,
+                 backoff: float = 0.5, sleep: Callable[[float], None] = time.sleep) -> Completion:
+    """Wrap a completion with exponential-backoff retries on any exception."""
+    def complete(prompt: str) -> str:
+        last: Optional[Exception] = None
+        for i in range(attempts):
+            try:
+                return completion(prompt)
+            except Exception as e:  # noqa: BLE001 - provider-agnostic retry
+                last = e
+                if i < attempts - 1:
+                    sleep(backoff * (2 ** i))
+        raise last  # type: ignore[misc]
+    return complete
+
+
+def claude(model: str = "claude-opus-4-8", max_tokens: int = 1024,
+           client: Optional[object] = None, **create_kwargs) -> Completion:
+    """A Claude-backed completion (requires ``pip install anthropic`` + creds).
+
+    Pass ``client`` to reuse an existing ``anthropic.Anthropic`` instance;
+    otherwise a default one is constructed lazily (resolving credentials from
+    the environment / an ``ant auth login`` profile). Use a cheaper ``model``
+    (e.g. ``"claude-haiku-4-5"``) for call-heavy loops."""
+    _client = client
+
+    def complete(prompt: str) -> str:
+        nonlocal _client
+        if _client is None:
+            from anthropic import Anthropic  # lazy, optional dependency
+            _client = Anthropic()
+        msg = _client.messages.create(
+            model=model, max_tokens=max_tokens,
+            messages=[{"role": "user", "content": prompt}], **create_kwargs,
+        )
+        return "".join(b.text for b in msg.content if b.type == "text")
+
+    return complete
+
+
+def openai_compatible(model: str, *, base_url_env: str = "OPENAI_BASE_URL",
+                      api_key_env: str = "OPENAI_API_KEY",
+                      default_base_url: str = "https://api.openai.com/v1",
+                      max_tokens: int = 1024, timeout: float = 120.0) -> Completion:
+    """A completion for any OpenAI-compatible chat endpoint (GLM/Zhipu, proxies,
+    local servers, OpenAI itself).
+
+    The base URL and API key are read from the environment at call time -- they
+    never pass through code or arguments. Point it at GLM, for example, by
+    setting ``OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4`` and
+    ``OPENAI_API_KEY=<your key>`` in your shell, then use ``model="glm-4.6"``."""
+    def complete(prompt: str) -> str:
+        base = os.environ.get(base_url_env, default_base_url).rstrip("/")
+        key = os.environ.get(api_key_env)
+        if not key:
+            raise RuntimeError(f"set {api_key_env} (and {base_url_env}) in your environment")
+        body = json.dumps({
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "max_tokens": max_tokens,
+        }).encode()
+        req = urllib.request.Request(
+            f"{base}/chat/completions", data=body,
+            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"})
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.load(resp)
+        return data["choices"][0]["message"]["content"]
+
+    return complete

agentdescent/aggregator.py

@@ -0,0 +1,370 @@
+"""The Aggregator: an optimizer over a discrete artifact space.
+
+This is where the central analogy deliberately breaks (design doc, section 1):
+gradients add, diffs do not.  Aggregation is therefore not averaging but
+**conflict resolution + statistical acceptance + transactional commit**.
+
+The per-bucket pipeline (design doc, section 4):
+
+    1. trigger + bucket        (section 4.1)
+    2. staleness filter        (section 4.2)  per-diff eta, three-way split
+       + rebase & cheap re-verify
+    3. conflict resolution     (section 4.3)  syntactic / semantic / PCGrad-drop
+       + candidate fusion tournament          (model-soup style)
+    4. Beta-posterior accept   (section 4.4)  P(delta > 0) > 1 - delta
+    5. CAS / 2PC commit        (section 4.1)
+    6. dual-branch promotion   (section 4.5)  EMA-style dev -> stable
+    7. audit submission        (section 5.3)  the optimizer audits itself
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Optional, Protocol, Tuple, runtime_checkable
+
+from .evolvable import Diff, EvidenceCard, Evolvable, VersionVector, vv_staleness
+from .governance import Layer, classify, assert_mutable
+from .ledger import CASConflict, Ledger
+from .scheduler import AuditScheduler
+from .staleness import StaleAction, StalenessPolicy, get_policy
+from .stats import BetaPosterior, annealed_delta, prob_improvement
+from .verifier import ThreeLayerVerifier
+
+
+@runtime_checkable
+class AggregatorProtocol(Protocol):
+    """The contract a custom aggregator must satisfy to plug into ``evolve``.
+
+    An aggregator is the framework's *optimizer*: it receives evidence cards
+    (diffs + evidence) and, on ``step()``, decides what to merge into the shared
+    ledger. Implement these two methods (see :class:`Aggregator` for the
+    reference 7-stage pipeline) to swap in your own merge/acceptance logic."""
+
+    def ingest(self, card: EvidenceCard) -> None: ...
+
+    def step(self) -> List["MergeReport"]: ...
+
+
+# Builds an aggregator from the runtime deps ``evolve`` owns. The default is the
+# reference :class:`Aggregator`; pass your own to ``evolve(aggregator_factory=)``.
+AggregatorFactory = Callable[
+    [Ledger, ThreeLayerVerifier, AuditScheduler, "AggregatorConfig", StalenessPolicy],
+    AggregatorProtocol,
+]
+
+
+@dataclass
+class AggregatorConfig:
+    batch_trigger: int = 4          # B: hot artifacts trigger by batch size
+    max_wait_rounds: int = 3        # T_max: cold artifacts trigger by time
+    base_delta: float = 0.5         # acceptance risk (annealed by version)
+    alpha_head: int = 5             # staleness tolerance for hot artifacts
+    alpha_tail: int = 1             # staleness tolerance for cold artifacts
+    trust_region_ops: int = 6       # max ops per diff (trust region)
+    promote_after_k: int = 3        # dev->stable survival rounds (EMA)
+
+
+@dataclass
+class MergeReport:
+    artifact_id: str
+    accepted: Optional[Diff]
+    fused: bool
+    considered: int
+    survived_staleness: int
+    discarded_stale: int
+    conflicts_dropped: int
+    prob_improve: float
+    committed_version: Optional[int]
+    reason: str = ""
+
+
+class EvidenceBuffer:
+    """Cards bucketed by target artifact (design doc, section 4.1).
+
+    Thread-safe: in the asynchronous runtime many worker threads call
+    :meth:`add` concurrently while the aggregator thread calls :meth:`ready` /
+    :meth:`drain`.  All bucket mutations are guarded by an internal lock."""
+
+    def __init__(self) -> None:
+        self._buckets: Dict[str, List[EvidenceCard]] = defaultdict(list)
+        self._waited: Dict[str, int] = defaultdict(int)
+        self._settled: List[EvidenceCard] = []
+        self._lock = threading.Lock()
+
+    def add(self, card: EvidenceCard) -> None:
+        with self._lock:
+            self._buckets[card.diff.target].append(card)
+
+    def tick(self) -> None:
+        with self._lock:
+            for aid in list(self._buckets):
+                self._waited[aid] += 1
+
+    def ready(self, config: AggregatorConfig) -> List[str]:
+        with self._lock:
+            out = []
+            for aid, cards in self._buckets.items():
+                if not cards:
+                    continue
+                if len(cards) >= config.batch_trigger or self._waited[aid] >= config.max_wait_rounds:
+                    out.append(aid)
+            return out
+
+    def drain(self, artifact_id: str) -> List[EvidenceCard]:
+        with self._lock:
+            cards = self._buckets.pop(artifact_id, [])
+            self._waited.pop(artifact_id, None)
+            return cards
+
+    def pending(self) -> int:
+        with self._lock:
+            return sum(len(c) for c in self._buckets.values())
+
+    def settle(self, cards: List[EvidenceCard]) -> None:
+        """Return discarded-diff evidence to the pool for later reuse.
+
+        This is the structural advantage of artifacts over gradients (design
+        doc, section 3.3): a stale gradient is simply lost, but a stale diff's
+        evidence survives.  Here we keep the cards addressable; a fuller system
+        would re-file them into the trajectory pool."""
+        with self._lock:
+            self._settled.extend(cards)
+
+    @property
+    def settled(self) -> List[EvidenceCard]:
+        with self._lock:
+            return list(self._settled)
+
+
+def diffs_conflict(a: Diff, b: Diff) -> bool:
+    """Syntactic overlap: do two diffs edit an overlapping set of keys?"""
+    return bool(set(a.ops) & set(b.ops))
+
+
+def diffs_contradict(a: Diff, b: Diff) -> bool:
+    """Semantic contradiction: same key, different proposed value."""
+    for k in set(a.ops) & set(b.ops):
+        if a.ops[k] != b.ops[k]:
+            return True
+    return False
+
+
+def fuse_diffs(diffs: List[Diff]) -> Diff:
+    """Merge complementary (non-contradicting) diffs into one candidate.
+
+    The model-soup analogy (design doc, section 4.3): the fusion of several
+    local improvements often beats any single one -- but only when they share a
+    base and do not contradict, which the caller guarantees."""
+    ops: Dict = {}
+    for d in diffs:
+        ops.update(d.ops)
+    ids = "+".join(sorted(d.diff_id for d in diffs))
+    breaking = any(d.contract_breaking for d in diffs)
+    return Diff(diff_id=f"fused({ids})", target=diffs[0].target, ops=ops,
+                contract_breaking=breaking, author="aggregator")
+
+
+class Aggregator:
+    """Per-artifact optimizer step over the ledger."""
+
+    def __init__(
+        self,
+        ledger: Ledger,
+        verifier: ThreeLayerVerifier,
+        audit: AuditScheduler,
+        config: Optional[AggregatorConfig] = None,
+        staleness_policy: Optional[StalenessPolicy] = None,
+    ) -> None:
+        self.ledger = ledger
+        self.verifier = verifier
+        self.audit = audit
+        # swap Full / Guarded / Reflective without touching the merge pipeline.
+        self.staleness_policy = staleness_policy or get_policy("guarded")
+        self.config = config or AggregatorConfig()
+        self.buffer = EvidenceBuffer()
+        self._posteriors: Dict[str, BetaPosterior] = defaultdict(BetaPosterior)
+        # dev-branch survival counter for EMA-style promotion.
+        self._survival: Dict[str, int] = defaultdict(int)
+
+    # -- staleness (section 4.2) ---------------------------------------------
+
+    def _alpha_for(self, artifact: Evolvable, card: EvidenceCard) -> int:
+        if card.diff.contract_breaking:
+            return 0  # contract-breaking diffs must be re-proposed, not rebased.
+        # hotter artifacts (bigger blast radius) tolerate more staleness.
+        return self.config.alpha_head if artifact.blast_radius > 0.5 else self.config.alpha_tail
+
+    def _staleness_filter(
+        self, artifact: Evolvable, head: VersionVector, cards: List[EvidenceCard]
+    ) -> Tuple[List[EvidenceCard], List[EvidenceCard]]:
+        """Split cards into (survivors, discarded), delegating to the policy.
+
+        The active :class:`~agentdescent.staleness.StalenessPolicy` (Full / Guarded
+        / Reflective) decides ACCEPT / REBASE / DISCARD from ``eta`` and
+        ``alpha``; the aggregator only executes the mechanical rebase-and-
+        re-verify for the REBASE case."""
+        survivors: List[EvidenceCard] = []
+        discarded: List[EvidenceCard] = []
+        for card in cards:
+            eta = vv_staleness(head, card.base_version)
+            alpha = self._alpha_for(artifact, card)
+            action = self.staleness_policy.decide(eta, alpha, card.diff.contract_breaking)
+            if action is StaleAction.ACCEPT:
+                survivors.append(card if eta == 0 else card.rebased_onto(head))
+            elif action is StaleAction.REBASE:
+                # cheaply re-verify the delta still holds on the current head.
+                candidate = artifact.apply(card.diff)
+                if artifact.cheap_eval(card) <= candidate.cheap_eval(card):
+                    survivors.append(card.rebased_onto(head))
+                else:
+                    discarded.append(card)
+            else:  # DISCARD
+                discarded.append(card)
+        return survivors, discarded
+
+    # -- conflict resolution (section 4.3) -----------------------------------
+
+    def _resolve_conflicts(
+        self, artifact: Evolvable, cards: List[EvidenceCard]
+    ) -> Tuple[List[EvidenceCard], int]:
+        """Drop contradicting diffs (PCGrad-style) and return surviving cards."""
+        dropped = 0
+        kept: List[EvidenceCard] = []
+        for card in cards:
+            conflict = False
+            for i, k in enumerate(kept):
+                if diffs_contradict(card.diff, k.diff):
+                    # project out the worse of the two on the held-out subset.
+                    d_score = self.verifier.cheap_eval(artifact.apply(card.diff))
+                    k_score = self.verifier.cheap_eval(artifact.apply(k.diff))
+                    if d_score > k_score:
+                        kept[i] = card
+                    dropped += 1
+                    conflict = True
+                    break
+            if not conflict:
+                kept.append(card)
+        return kept, dropped
+
+    # -- fusion tournament (section 4.3) -------------------------------------
+
+    def _tournament(self, artifact: Evolvable, diffs: List[Diff]) -> Tuple[Diff, Evolvable, bool]:
+        """Run candidates (plus their fusion) in a held-out tournament."""
+        candidates: List[Tuple[Diff, Evolvable, bool]] = []
+        for d in diffs:
+            candidates.append((d, artifact.apply(d), False))
+        # add a fused candidate if the survivors are mutually complementary.
+        if len(diffs) > 1 and not any(
+            diffs_contradict(a, b) for i, a in enumerate(diffs) for b in diffs[i + 1:]
+        ):
+            fused = fuse_diffs(diffs)
+            candidates.append((fused, artifact.apply(fused), True))
+
+        best = max(candidates, key=lambda c: self.verifier.cheap_eval(c[1]))
+        return best
+
+    # -- public entry points -------------------------------------------------
+
+    def ingest(self, card: EvidenceCard) -> None:
+        self.buffer.add(card)
+
+    def step(self) -> List[MergeReport]:
+        """Fire every artifact bucket that is ready and return per-artifact reports."""
+        self.buffer.tick()
+        reports: List[MergeReport] = []
+        for aid in self.buffer.ready(self.config):
+            reports.append(self._process(aid))
+        return reports
+
+    def _process(self, artifact_id: str) -> MergeReport:
+        cards = self.buffer.drain(artifact_id)
+        snap = self.ledger.snapshot(Ledger.DEV)
+        artifact = snap.get(artifact_id)
+        if artifact is None:
+            return MergeReport(artifact_id, None, False, len(cards), 0, 0, 0, 0.0, None,
+                               "unknown artifact")
+        assert_mutable(artifact)  # L0 guard
+
+        # trust-region: reject over-large diffs up front.
+        cards = [c for c in cards if c.diff.size() <= self.config.trust_region_ops]
+
+        head = snap.version
+        survivors, discarded = self._staleness_filter(artifact, head, cards)
+        self.buffer.settle(discarded)
+        if not survivors:
+            return MergeReport(artifact_id, None, False, len(cards), 0, len(discarded),
+                               0, 0.0, None, "all stale / rejected")
+
+        kept_cards, conflicts = self._resolve_conflicts(artifact, survivors)
+        kept_diffs = [c.diff for c in kept_cards]
+        best_diff, best_state, fused = self._tournament(artifact, kept_diffs)
+
+        # -- Beta-posterior acceptance (section 4.4) -------------------------
+        # Compare candidate vs base as two Beta posteriors over their held-out
+        # success rate, with the running per-artifact posterior as a shared
+        # prior (so evidence-starved tail artifacts get a wider, more
+        # conservative test).  Accept iff P(candidate_rate > base_rate) clears
+        # the annealed threshold -- not a point estimate crossing a line.
+        prior = self._posteriors[artifact_id]
+        base_s, base_f = self.verifier.eval_counts(artifact)
+        cand_s, cand_f = self.verifier.eval_counts(best_state)
+        base_score = self.verifier.cheap_eval(artifact)
+        cand_score = self.verifier.cheap_eval(best_state)
+
+        baseline_post = BetaPosterior(prior.successes + base_s, prior.failures + base_f)
+        candidate_post = BetaPosterior(prior.successes + cand_s, prior.failures + cand_f)
+        # fold each contributing worker's local before/after delta as extra
+        # evidence for the candidate (the "gradient magnitude").
+        for card in kept_cards:
+            if set(card.diff.ops) & set(best_diff.ops):
+                candidate_post.observe_delta(card.before_after_delta)
+
+        delta = annealed_delta(self.config.base_delta, artifact.version)
+        p_improve = prob_improvement(candidate_post, baseline_post, seed=artifact.version)
+
+        # -- audit (section 5.3): the optimizer audits its own decision ------
+        _, uncertainty = self.verifier.learned_eval(best_state)
+        self.audit.submit(best_diff.diff_id, artifact_id, artifact.blast_radius,
+                          uncertainty, payload=best_diff)
+        if self.audit.force_oracle(artifact.blast_radius, artifact_id):
+            oracle_base = self.verifier.oracle_eval(artifact)
+            oracle_cand = self.verifier.oracle_eval(best_state)
+            agreed = (oracle_cand > oracle_base) == (cand_score > base_score)
+            self.audit.update_trust(artifact_id, agreed)
+            if oracle_cand <= oracle_base:
+                prior.observe_delta(oracle_cand - oracle_base)
+                return MergeReport(artifact_id, None, fused, len(cards), len(survivors),
+                                   len(discarded), conflicts, p_improve, None,
+                                   "oracle rejected")
+
+        if p_improve <= 1.0 - delta or cand_score < base_score:
+            prior.observe_delta(cand_score - base_score)
+            return MergeReport(artifact_id, None, fused, len(cards), len(survivors),
+                               len(discarded), conflicts, p_improve, None,
+                               f"P(delta>0)={p_improve:.2f} <= {1-delta:.2f}")
+
+        # -- commit (section 4.1): CAS on dev --------------------------------
+        base_vv = {artifact_id: head.get(artifact_id, 0)}
+        try:
+            _, new_version = self.ledger.commit(
+                best_state, base_vv, branch=Ledger.DEV,
+                message=f"merge {best_diff.diff_id} -> {artifact_id}",
+            )
+        except CASConflict:
+            self.buffer.settle(survivors)
+            return MergeReport(artifact_id, None, fused, len(cards), len(survivors),
+                               len(discarded), conflicts, p_improve, None, "CAS conflict")
+
+        prior.update(True, weight=2.0)  # a committed improvement is strong evidence.
+
+        # -- dual-branch EMA promotion (section 4.5) -------------------------
+        self._survival[artifact_id] += 1
+        if self._survival[artifact_id] >= self.config.promote_after_k:
+            self.ledger.promote_to_stable(artifact_id)
+            self._survival[artifact_id] = 0
+
+        return MergeReport(artifact_id, best_diff, fused, len(cards), len(survivors),
+                           len(discarded), conflicts, p_improve, new_version,
+                           "committed")