loopx 0.4.8__py3-none-any.whl

loopx/capabilities/explore/router_state.py

@@ -0,0 +1,432 @@
+from __future__ import annotations
+
+import math
+from copy import deepcopy
+from typing import Any, Mapping, Sequence
+
+
+ROUTER_STATE_SCHEMA_VERSION = "loopx_explore_router_state_v0"
+
+# Every first-seen observation key is worth one unit; anything richer (domain
+# flags and their weights) is the adapter's business and arrives per record as
+# ``weighted_flags`` -- this module must stay free of domain vocabulary.
+OBSERVATION_WEIGHT = 1.0
+
+DEFAULT_ROUTER_CONFIG: dict[str, Any] = {
+    "value_rate_alpha": 0.3,
+    "duration_alpha": 0.3,
+    "accept_rate_alpha": 0.3,
+    "infra_alpha": 0.5,
+    "bias_gamma": 0.1,
+    "bias_decay": 0.95,
+    "bias_clamp": 0.5,
+    "coverage_horizon_epochs": 4,
+    "surplus_share_factor": 2.0,
+    "surplus_novelty_ceiling": 0.1,
+    "ucb_coefficient": 0.6,
+    "ucb_cap": 1.5,
+    "coverage_bonus_cap": 0.5,
+    "novelty_floor": 0.05,
+    "novelty_debt_threshold": 0.05,
+    "infra_penalty_weight": 0.5,
+    "cold_start_value_rate": 1.0,
+    "cold_start_duration_minutes": 1.0,
+    "cold_start_accept_rate": 0.8,
+    "routing_multiplier_floor": 0.05,
+}
+
+_MIN_DURATION_MINUTES = 0.05
+
+
+def scope_family_key(family: str) -> str:
+    """Canonical router family id for a task family.
+
+    Executing harnesses declare a work item's family through its write scope
+    (``artifacts/<family>/**``), which the planner's ``_affinity_key``
+    collapses to ``scope:artifacts/<family>``. Keeping this mapping in one
+    exported helper ties the harness's family taxonomy and the planner's
+    affinity buckets into a single expert id space.
+    """
+
+    clean = str(family or "").strip().strip("/")
+    return f"scope:artifacts/{clean}" if clean else "topic:general"
+
+
+# Deprecated alias kept for existing callers; prefer scope_family_key.
+family_key_for_probe_task = scope_family_key
+
+
+def initial_router_state(config: Mapping[str, Any] | None = None) -> dict[str, Any]:
+    merged = dict(DEFAULT_ROUTER_CONFIG)
+    for key, value in dict(config or {}).items():
+        if key in merged:
+            merged[key] = value
+    return {
+        "schema_version": ROUTER_STATE_SCHEMA_VERSION,
+        "config": merged,
+        "updated_epoch": 0,
+        "totals": {"dispatches": 0, "observed_epochs": 0},
+        "seen_observation_keys": [],
+        "families": {},
+        "last_epoch": {"epoch": 0, "minutes_by_family": {}, "novel_value_by_family": {}},
+    }
+
+
+def _config(state: Mapping[str, Any]) -> dict[str, Any]:
+    merged = dict(DEFAULT_ROUTER_CONFIG)
+    for key, value in dict(state.get("config") or {}).items():
+        if key in merged:
+            merged[key] = value
+    return merged
+
+
+def _blank_family() -> dict[str, Any]:
+    return {
+        "value_rate_ema": None,
+        "duration_ema": None,
+        "accept_rate_ema": None,
+        "novelty_rate": None,
+        "infra_ema": 0.0,
+        "runs": 0,
+        "last_run_epoch": None,
+        "bias": 0.0,
+    }
+
+
+def _ema(previous: float | None, sample: float, alpha: float) -> float:
+    if previous is None:
+        return float(sample)
+    return (1.0 - alpha) * float(previous) + alpha * float(sample)
+
+
+def _flag_pseudo_key(family: str, flag: str) -> str:
+    # Flags are family-scoped facts (the same flag raised in family X and
+    # family Y is two different signals); raw observation keys are global so
+    # that splitting a family can never re-mint an already-seen key as novel.
+    return f"flag:{family}:{flag}"
+
+
+def observe_epoch(
+    state: Mapping[str, Any],
+    *,
+    epoch: int,
+    probes: Sequence[Mapping[str, Any]],
+) -> dict[str, Any]:
+    """Fold one epoch of probe outcomes into a new router state.
+
+    Each probe mapping carries: ``family`` (canonical family id), ``duration_minutes``,
+    ``observation_keys`` (list), ``accepted`` (bool), ``retryable_infra_error``
+    (bool), and ``weighted_flags``: ``{flag_name: weight}`` for value-bearing
+    flags that are TRUE. A probe that folds several sibling executions (an
+    episode group) may additionally carry ``accepted_count`` and
+    ``attempt_count`` so acceptance is weighted by the number of suffix
+    attempts. Invalid or absent counts fall back to the legacy ``accepted``
+    boolean. The adapter owns both flag names and weights; this module never
+    hardcodes domain vocabulary.
+
+    Value-rate EMAs use RAW value per minute (not novelty-discounted) so the
+    estimator measures the environment, not the router's own rerun policy;
+    depletion is tracked separately as ``novelty_rate`` from the global
+    first-seen ledger. Bias is deliberately NOT touched here -- it only moves
+    in :func:`advance_epoch`, and it must never feed back into these value
+    statistics (aux-loss-free invariant: bias steers routing order only).
+    """
+
+    next_state = deepcopy(dict(state))
+    config = _config(next_state)
+    families: dict[str, Any] = next_state.setdefault("families", {})
+    seen: set[str] = set(next_state.get("seen_observation_keys") or [])
+
+    minutes_by_family: dict[str, float] = {}
+    novel_value_by_family: dict[str, float] = {}
+    per_family_samples: dict[str, dict[str, list[float]]] = {}
+
+    for probe in probes:
+        family = str(probe.get("family") or "topic:general")
+        duration = max(_MIN_DURATION_MINUTES, float(probe.get("duration_minutes") or 0.0))
+        observation_keys = [str(key) for key in probe.get("observation_keys") or []]
+        weighted = probe.get("weighted_flags")
+        true_flags = (
+            {str(name): float(weight) for name, weight in weighted.items()}
+            if isinstance(weighted, Mapping)
+            else {}
+        )
+
+        raw_value = float(len(observation_keys)) * OBSERVATION_WEIGHT
+        raw_value += sum(true_flags.values())
+
+        novel_value = 0.0
+        for key in observation_keys:
+            if key not in seen:
+                seen.add(key)
+                novel_value += OBSERVATION_WEIGHT
+        for flag, weight in true_flags.items():
+            pseudo = _flag_pseudo_key(family, flag)
+            if pseudo not in seen:
+                seen.add(pseudo)
+                novel_value += weight
+
+        samples = per_family_samples.setdefault(
+            family,
+            {
+                "value_rate": [],
+                "duration": [],
+                "novelty": [],
+                "accept": [],
+                "accept_weight": [],
+                "infra": [],
+            },
+        )
+        samples["value_rate"].append(raw_value / duration)
+        samples["duration"].append(duration)
+        samples["novelty"].append(novel_value / raw_value if raw_value > 0 else 0.0)
+        accept_sample = 1.0 if probe.get("accepted") else 0.0
+        accept_weight = 1.0
+        accepted_count = probe.get("accepted_count")
+        attempt_count = probe.get("attempt_count")
+        if accepted_count is not None or attempt_count is not None:
+            try:
+                accepted_total = float(accepted_count)
+                attempt_total = float(attempt_count)
+            except (OverflowError, TypeError, ValueError):
+                pass
+            else:
+                counts_are_valid = (
+                    not isinstance(accepted_count, bool)
+                    and not isinstance(attempt_count, bool)
+                    and math.isfinite(accepted_total)
+                    and math.isfinite(attempt_total)
+                    and accepted_total.is_integer()
+                    and attempt_total.is_integer()
+                    and attempt_total > 0
+                    and 0 <= accepted_total <= attempt_total
+                )
+                if counts_are_valid:
+                    accept_sample = accepted_total / attempt_total
+                    accept_weight = attempt_total
+        samples["accept"].append(accept_sample)
+        samples["accept_weight"].append(accept_weight)
+        samples["infra"].append(1.0 if probe.get("retryable_infra_error") else 0.0)
+
+        minutes_by_family[family] = minutes_by_family.get(family, 0.0) + duration
+        novel_value_by_family[family] = novel_value_by_family.get(family, 0.0) + novel_value
+
+    for family, samples in per_family_samples.items():
+        record = families.setdefault(family, _blank_family())
+        run_count = len(samples["value_rate"])
+        mean = lambda values: sum(values) / max(1, len(values))  # noqa: E731
+        record["value_rate_ema"] = round(
+            _ema(record.get("value_rate_ema"), mean(samples["value_rate"]), config["value_rate_alpha"]), 4
+        )
+        record["duration_ema"] = round(
+            _ema(record.get("duration_ema"), mean(samples["duration"]), config["duration_alpha"]), 4
+        )
+        accept_weight_total = sum(samples["accept_weight"])
+        accept_mean = sum(
+            value * weight
+            for value, weight in zip(samples["accept"], samples["accept_weight"])
+        ) / max(1.0, accept_weight_total)
+        record["accept_rate_ema"] = round(
+            _ema(record.get("accept_rate_ema"), accept_mean, config["accept_rate_alpha"]), 4
+        )
+        record["infra_ema"] = round(
+            _ema(record.get("infra_ema") or 0.0, mean(samples["infra"]), config["infra_alpha"]), 4
+        )
+        record["novelty_rate"] = round(mean(samples["novelty"]), 4)
+        record["runs"] = int(record.get("runs") or 0) + run_count
+        record["last_run_epoch"] = int(epoch)
+
+    totals = next_state.setdefault("totals", {"dispatches": 0, "observed_epochs": 0})
+    totals["dispatches"] = int(totals.get("dispatches") or 0) + len(list(probes))
+    totals["observed_epochs"] = int(totals.get("observed_epochs") or 0) + 1
+    next_state["seen_observation_keys"] = sorted(seen)
+    next_state["last_epoch"] = {
+        "epoch": int(epoch),
+        "minutes_by_family": {key: round(value, 4) for key, value in minutes_by_family.items()},
+        "novel_value_by_family": {key: round(value, 4) for key, value in novel_value_by_family.items()},
+    }
+    return next_state
+
+
+def predicted_novelty(state: Mapping[str, Any], family: str) -> float:
+    """Predicted fraction of the next run's value that would be first-seen."""
+
+    config = _config(state)
+    record = (state.get("families") or {}).get(family)
+    if not record or not int(record.get("runs") or 0):
+        return 1.0
+    last = record.get("novelty_rate")
+    if last is None:
+        return 1.0
+    return max(float(config["novelty_floor"]), float(last))
+
+
+def advance_epoch(
+    state: Mapping[str, Any],
+    *,
+    epoch: int,
+    eligible_families: Sequence[str],
+) -> dict[str, Any]:
+    """Update per-family routing bias at an epoch boundary (aux-loss-free analog).
+
+    DeepSeek-V3 updates a per-expert bias by +/-gamma from over/underload and
+    applies it to top-k selection only. The harness analog replaces "load
+    equality" (worthless here -- rerunning a depleted family at fair share is
+    pure waste) with coverage/novelty debt:
+
+    - debt: family has eligible work, has not run for > coverage_horizon
+      epochs, and is still predicted to yield novel value;
+    - surplus: family consumed > surplus_share_factor x fair share of the last
+      epoch's dispatched minutes while returning near-pure duplicates.
+
+    The bias decays toward zero (windup guard on frozen todo pools) and is
+    clamped. It must only ever be read for routing ORDER -- never mixed into
+    value estimates, plan evidence, or reported metrics.
+    """
+
+    next_state = deepcopy(dict(state))
+    config = _config(next_state)
+    families: dict[str, Any] = next_state.setdefault("families", {})
+    eligible = [str(family) for family in eligible_families]
+    for family in eligible:
+        families.setdefault(family, _blank_family())
+
+    last_epoch = next_state.get("last_epoch") or {}
+    minutes_by_family = {
+        str(key): float(value)
+        for key, value in (last_epoch.get("minutes_by_family") or {}).items()
+    }
+    total_minutes = sum(minutes_by_family.values())
+    fair_share = total_minutes / max(1, len(eligible)) if eligible else 0.0
+
+    horizon = max(1, int(config["coverage_horizon_epochs"]))
+    gamma = float(config["bias_gamma"])
+    decay = float(config["bias_decay"])
+    clamp = abs(float(config["bias_clamp"]))
+
+    for family, record in families.items():
+        debt = 0
+        surplus = 0
+        if family in eligible:
+            last_run = record.get("last_run_epoch")
+            epochs_since = (
+                int(epoch) - int(last_run) if last_run is not None else horizon + 1
+            )
+            if epochs_since > horizon and predicted_novelty(next_state, family) > float(
+                config["novelty_debt_threshold"]
+            ):
+                debt = 1
+            spent = minutes_by_family.get(family, 0.0)
+            novelty = record.get("novelty_rate")
+            if (
+                fair_share > 0
+                and spent > float(config["surplus_share_factor"]) * fair_share
+                and novelty is not None
+                and float(novelty) < float(config["surplus_novelty_ceiling"])
+            ):
+                surplus = 1
+        bias = decay * float(record.get("bias") or 0.0) + gamma * (debt - surplus)
+        record["bias"] = round(max(-clamp, min(clamp, bias)), 4)
+
+    next_state["updated_epoch"] = int(epoch)
+    return next_state
+
+
+def family_routing_terms(
+    state: Mapping[str, Any],
+    family: str,
+) -> dict[str, Any]:
+    """Routing terms for one family, split into value vs routing-only parts.
+
+    ``expected_value_rate`` (value_rate x predicted novelty) is the unbiased
+    bookkeeping quantity: it may feed plan evidence, bundle sizing, and
+    admission. ``routing_multiplier`` additionally folds in exploration
+    (UCB), coverage recency, bias, and infra penalty -- it may only reorder
+    candidates. Keeping the split explicit is the DeepSeek-V3 invariant that
+    the old hard coverage floor violated.
+    """
+
+    config = _config(state)
+    families = state.get("families") or {}
+    record = families.get(family) or {}
+    runs = int(record.get("runs") or 0)
+
+    known_rates = [
+        float(item.get("value_rate_ema"))
+        for item in families.values()
+        if item.get("value_rate_ema") is not None
+    ]
+    cold_start_rate = (
+        sum(known_rates) / len(known_rates)
+        if known_rates
+        else float(config["cold_start_value_rate"])
+    )
+    value_rate = (
+        float(record["value_rate_ema"])
+        if record.get("value_rate_ema") is not None
+        else cold_start_rate
+    )
+    novelty = predicted_novelty(state, family)
+
+    total_dispatches = int((state.get("totals") or {}).get("dispatches") or 0)
+    ucb = min(
+        float(config["ucb_cap"]),
+        float(config["ucb_coefficient"])
+        * math.sqrt(math.log(1.0 + total_dispatches) / (runs + 1.0)),
+    )
+
+    last_run = record.get("last_run_epoch")
+    updated_epoch = int(state.get("updated_epoch") or 0)
+    horizon = max(1, int(config["coverage_horizon_epochs"]))
+    if runs and last_run is not None:
+        epochs_since = max(0, updated_epoch - int(last_run))
+    else:
+        epochs_since = horizon
+    coverage_bonus = float(config["coverage_bonus_cap"]) * min(1.0, epochs_since / horizon)
+
+    bias = float(record.get("bias") or 0.0)
+    infra_penalty = float(config["infra_penalty_weight"]) * float(record.get("infra_ema") or 0.0)
+
+    expected_value_rate = value_rate * novelty
+    unbiased_multiplier = max(
+        float(config["routing_multiplier_floor"]),
+        1.0 + ucb + coverage_bonus - infra_penalty,
+    )
+    routing_multiplier = max(
+        float(config["routing_multiplier_floor"]),
+        1.0 + ucb + coverage_bonus + bias - infra_penalty,
+    )
+    duration = (
+        float(record["duration_ema"])
+        if record.get("duration_ema") is not None
+        else float(config["cold_start_duration_minutes"])
+    )
+    accept_rate = (
+        float(record["accept_rate_ema"])
+        if record.get("accept_rate_ema") is not None
+        else float(config["cold_start_accept_rate"])
+    )
+    return {
+        "family": family,
+        "runs": runs,
+        "value_rate": round(value_rate, 4),
+        "novelty": round(novelty, 4),
+        "expected_value_rate": round(expected_value_rate, 4),
+        "duration_minutes": round(duration, 4),
+        "duration_observed": record.get("duration_ema") is not None,
+        "accept_rate": round(accept_rate, 4),
+        "ucb": round(ucb, 4),
+        "coverage_bonus": round(coverage_bonus, 4),
+        "bias": round(bias, 4),
+        "infra_penalty": round(infra_penalty, 4),
+        "routing_multiplier": round(routing_multiplier, 4),
+        "routing_value": round(expected_value_rate * routing_multiplier, 4),
+        "unbiased_routing_value": round(expected_value_rate * unbiased_multiplier, 4),
+    }
+
+
+def is_router_state(value: Any) -> bool:
+    return (
+        isinstance(value, Mapping)
+        and str(value.get("schema_version") or "").startswith("loopx_explore_router_state")
+    )

loopx/capabilities/explore/source_history_reconcile.py

@@ -0,0 +1,255 @@
+"""Reconcile a canonical Explore result source from a public-safe candidate log."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections import Counter
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from .result_log import (
+    EVENT_KIND_EDGE,
+    EVENT_KIND_FINDING,
+    EVENT_KIND_NODE,
+    PUBLIC_BOUNDARY,
+    append_explore_result_events,
+    build_explore_result_projection,
+    load_explore_result_events_strict,
+)
+
+
+SCHEMA_VERSION = "loopx_explore_source_history_reconcile_v0"
+_TABLE_BY_EVENT_KIND = {
+    EVENT_KIND_NODE: "nodes",
+    EVENT_KIND_EDGE: "edges",
+    EVENT_KIND_FINDING: "findings",
+}
+_PROJECTION_COLLECTIONS = (
+    ("nodes", "node_id"),
+    ("edges", "edge_id"),
+    ("findings", "finding_id"),
+)
+
+
+def _digest(values: Sequence[str] | set[str]) -> str | None:
+    normalized = sorted(set(values))
+    if not normalized:
+        return None
+    encoded = json.dumps(normalized, ensure_ascii=True, separators=(",", ":"))
+    return hashlib.sha256(encoded.encode("utf-8")).hexdigest()[:16]
+
+
+def _source_ref_digest(path: Path) -> str:
+    return hashlib.sha256(str(path.expanduser().resolve()).encode("utf-8")).hexdigest()[:16]
+
+
+def _projection_result_keys(projection: Mapping[str, Any], *, goal_id: str) -> set[str]:
+    keys: set[str] = set()
+    for table_key, result_id_key in _PROJECTION_COLLECTIONS:
+        for item in projection.get(table_key) or []:
+            if not isinstance(item, Mapping):
+                continue
+            result_id = str(item.get(result_id_key) or "").strip()
+            if result_id:
+                keys.add(f"{goal_id}:{table_key}:{result_id}")
+    return keys
+
+
+def _projection(events: Sequence[Mapping[str, Any]], *, goal_id: str) -> dict[str, Any]:
+    return build_explore_result_projection(
+        events,
+        goal_id=goal_id,
+        finding_limit=len(events),
+        mermaid_node_limit=max(1, len(events)),
+    )
+
+
+def _by_table(keys: set[str], *, goal_id: str) -> dict[str, int]:
+    prefix = f"{goal_id}:"
+    counts: Counter[str] = Counter()
+    for key in keys:
+        suffix = key.removeprefix(prefix)
+        counts[suffix.split(":", 1)[0]] += 1
+    return dict(sorted(counts.items()))
+
+
+def _latest_by_result_id(
+    events: Sequence[Mapping[str, Any]],
+) -> dict[str, dict[str, Any]]:
+    latest: dict[str, dict[str, Any]] = {}
+    for event in events:
+        result_id = str(event.get("result_id") or "").strip()
+        if result_id:
+            latest[result_id] = dict(event)
+    return latest
+
+
+def _direct_projection_key(event: Mapping[str, Any], *, goal_id: str) -> str:
+    table = _TABLE_BY_EVENT_KIND[str(event["event_kind"])]
+    return f"{goal_id}:{table}:{event['result_id']}"
+
+
+def _materialized_parent_edge_keys(projection: Mapping[str, Any], *, goal_id: str) -> set[str]:
+    return {
+        f"{goal_id}:edges:{edge['edge_id']}"
+        for edge in projection.get("edges") or []
+        if isinstance(edge, Mapping) and edge.get("materialized_from") == "node_parent_id" and edge.get("edge_id")
+    }
+
+
+def reconcile_explore_source_history(
+    *,
+    canonical_log_path: Path,
+    candidate_log_path: Path,
+    goal_id: str,
+    registered_result_keys: Sequence[str] | set[str],
+    execute: bool = False,
+) -> dict[str, Any]:
+    """Recover registered public-safe results without deleting remote rows.
+
+    Only the latest canonical event for a result id absent from the canonical
+    source is eligible. Its direct projection key must already exist in the
+    registered sink baseline. Derived rows that remain absent are classified,
+    never synthesized or deleted by this non-destructive command.
+    """
+
+    canonical_events = load_explore_result_events_strict(canonical_log_path, goal_id=goal_id)
+    candidate_events = load_explore_result_events_strict(candidate_log_path, goal_id=goal_id)
+    registered = {
+        str(key)
+        for key in registered_result_keys
+        if any(str(key).startswith(f"{goal_id}:{table}:") for table in _TABLE_BY_EVENT_KIND.values())
+    }
+    if not registered:
+        raise ValueError("Explore source reconciliation requires a registered sink baseline")
+
+    canonical_projection = _projection(canonical_events, goal_id=goal_id)
+    candidate_projection = _projection(candidate_events, goal_id=goal_id)
+    canonical_keys = _projection_result_keys(canonical_projection, goal_id=goal_id)
+    candidate_keys = _projection_result_keys(candidate_projection, goal_id=goal_id)
+    missing_before = registered - canonical_keys
+
+    canonical_result_ids = {str(event.get("result_id") or "") for event in canonical_events}
+    candidate_latest = _latest_by_result_id(candidate_events)
+    selected_events = [
+        event
+        for result_id, event in candidate_latest.items()
+        if result_id not in canonical_result_ids and _direct_projection_key(event, goal_id=goal_id) in missing_before
+    ]
+    selected_events.sort(
+        key=lambda event: (
+            str(event.get("recorded_at") or ""),
+            str(event.get("event_id") or ""),
+        )
+    )
+
+    planned_events = [*canonical_events, *selected_events]
+    planned_projection = _projection(planned_events, goal_id=goal_id)
+    planned_keys = _projection_result_keys(planned_projection, goal_id=goal_id)
+    newly_projected = planned_keys - canonical_keys
+    unexpected_new = newly_projected - registered
+    if unexpected_new:
+        raise ValueError("candidate history would add projection rows outside the registered baseline")
+
+    recovered = missing_before & planned_keys
+    remaining = registered - planned_keys
+    stale_parent_edges = remaining & _materialized_parent_edge_keys(candidate_projection, goal_id=goal_id)
+    unresolved_orphans = remaining - stale_parent_edges
+    selected_event_ids = {str(event.get("event_id") or "") for event in selected_events}
+
+    writeback = {
+        "performed": False,
+        "requested_event_count": len(selected_events),
+        "appended_event_count": 0,
+        "reused_event_count": 0,
+        "readback_verified": None,
+    }
+    post_keys = canonical_keys
+    if execute and selected_events:
+        append_receipt = append_explore_result_events(
+            canonical_log_path,
+            selected_events,
+            expected_goal_id=goal_id,
+        )
+        post_events = load_explore_result_events_strict(canonical_log_path, goal_id=goal_id)
+        post_event_ids = {str(event.get("event_id") or "") for event in post_events}
+        post_projection = _projection(post_events, goal_id=goal_id)
+        post_keys = _projection_result_keys(post_projection, goal_id=goal_id)
+        readback_verified = bool(
+            selected_event_ids <= post_event_ids
+            and planned_keys <= post_keys
+            and not (registered & planned_keys) - post_keys
+        )
+        if not readback_verified:
+            raise RuntimeError("Explore source reconciliation readback failed")
+        writeback.update(
+            {
+                "performed": True,
+                "appended_event_count": int(append_receipt["appended_event_count"]),
+                "reused_event_count": int(append_receipt["reused_event_count"]),
+                "readback_verified": True,
+            }
+        )
+
+    effective_keys = post_keys if execute else planned_keys
+    effective_remaining = registered - effective_keys
+    if selected_events:
+        status = "reconciled" if execute else "would_reconcile"
+    else:
+        status = "already_reconciled"
+    if effective_remaining:
+        status += "_with_remote_orphans"
+
+    return {
+        "ok": True,
+        "schema_version": SCHEMA_VERSION,
+        "goal_id": goal_id,
+        "execute": bool(execute),
+        "status": status,
+        "source_refs": {
+            "canonical_sha256_16": _source_ref_digest(canonical_log_path),
+            "candidate_sha256_16": _source_ref_digest(candidate_log_path),
+            "raw_paths_returned": False,
+        },
+        "source_counts": {
+            "canonical_event_count": len(canonical_events),
+            "candidate_event_count": len(candidate_events),
+            "candidate_result_count": len(candidate_latest),
+        },
+        "plan": {
+            "selected_event_count": len(selected_events),
+            "selected_event_ids_sha256_16": _digest(selected_event_ids),
+            "latest_event_per_missing_result": True,
+            "raw_history_copied": False,
+        },
+        "projection_reconciliation": {
+            "canonical_result_count": len(canonical_keys),
+            "candidate_result_count": len(candidate_keys),
+            "registered_result_count": len(registered),
+            "missing_before_count": len(missing_before),
+            "missing_before_by_table": _by_table(missing_before, goal_id=goal_id),
+            "recovered_lost_history_count": len(recovered),
+            "recovered_lost_history_by_table": _by_table(recovered, goal_id=goal_id),
+            "recovered_lost_history_sha256_16": _digest(recovered),
+            "remaining_registered_result_count": len(effective_remaining),
+            "remaining_registered_by_table": _by_table(effective_remaining, goal_id=goal_id),
+            "remaining_registered_sha256_16": _digest(effective_remaining),
+            "unexpected_new_result_count": len(unexpected_new),
+        },
+        "classification": {
+            "lost_history_recovered_count": len(recovered),
+            "stale_materialized_parent_edge_count": len(stale_parent_edges),
+            "unresolved_orphan_count": len(unresolved_orphans),
+            "remote_deletion_required": bool(effective_remaining),
+            "remote_deletion_performed": False,
+        },
+        "writeback": writeback,
+        "boundary": {
+            **PUBLIC_BOUNDARY,
+            "candidate_events_strictly_validated": True,
+            "registered_baseline_only": True,
+            "destructive_remote_action_performed": False,
+        },
+    }