agent-learning-kit 0.1.0__py3-none-any.whl

fi/alk/practice/__init__.py

@@ -0,0 +1,51 @@
+"""Phase 13D — the Practice Loop trainer (facade only; mirrors live/ style).
+
+Lazy exports so ``import fi.alk.practice`` stays cheap. The trainer
+employs the existing 13C operators; it adds no new step API and emits standard
+``agent-learning.run.v1`` rows through ``run_manifest``/``public_payload`` so
+every episode lands a telemetry ledger row with zero new telemetry code.
+"""
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+# public name → home submodule (resolved lazily)
+_LAZY_EXPORTS = {
+    # contract constants
+    "PRACTICE_PHASES": "_contract",
+    "PRACTICE_ARTIFACT_KINDS": "_contract",
+    "SCAFFOLD_TYPES": "_contract",
+    "LADDER_STATES": "_contract",
+    "PRACTICE_REPLAY_INTERVALS": "_contract",
+    "ZPD_BAND": "_contract",
+    "REVIEW_RATIO": "_contract",
+    "BUDGET_PLAN": "_contract",
+    "PRACTICE_STORE_ACTIVE_CAP": "_contract",
+    "SCAFFOLD_FADE_DEFAULT": "_contract",
+    "AGENT_LEARNING_PRACTICE_LOOP_KIND": "_contract",
+    "AGENT_LEARNING_PRACTICE_RESULT_KIND": "_contract",
+    "practice_store_path": "_contract",
+    # budget
+    "BudgetMeter": "_budget",
+    "BudgetExhausted": "_budget",
+    # trainer surface
+    "run_practice_loop": "_trainer",
+    "practice_report": "_assess",
+    "ladder_state": "_store",
+    "run_due_reviews": "_schedule",
+}
+
+
+def __getattr__(name: str) -> Any:
+    home = _LAZY_EXPORTS.get(name)
+    if home is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module = importlib.import_module(f"{__name__}.{home}")
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY_EXPORTS))

fi/alk/practice/_assess.py

@@ -0,0 +1,103 @@
+"""Unit 10 (BBG U10 / ARCH §2d phase 1) — ASSESS: battery over the obligation grid.
+
+Runs the battery over ``scenarios × cast × perturbations`` at ScenarioBinding
+weights by deriving run manifests per cell (each scored episode charges the
+meter), collecting verdict rows via loss.verdict_row, composing loss.loss_report.
+Emits ``agent-learning.practice-report.v1`` through public_payload.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Mapping, Optional
+
+from .._schema import public_payload
+from .. import loss as _loss
+from ._budget import BudgetMeter
+from ._contract import AGENT_LEARNING_PRACTICE_REPORT_KIND
+
+
+def _grid_cells(simulation: Mapping[str, Any]) -> List[dict]:
+    """Enumerate obligation cells from the P7 CoverageDeclaration vocabulary;
+    degenerate single cell when no coverage declared."""
+    cells: List[dict] = []
+    for binding in simulation.get("scenarios") or []:
+        scenario = binding.get("scenario") or {}
+        coverage = scenario.get("coverage") or {}
+        intents = coverage.get("intents") or [None]
+        perturbations = coverage.get("perturbations") or [None]
+        for member in binding.get("cast") or []:
+            for intent in intents:
+                for perturbation in perturbations:
+                    cells.append({
+                        "intent": intent,
+                        "persona": member.get("persona"),
+                        "perturbation": perturbation,
+                        "obligation": None,
+                        "weight": float(binding.get("weight", 1.0)),
+                    })
+    if not cells:
+        cells.append({"intent": None, "persona": None, "perturbation": None,
+                      "obligation": None, "weight": 1.0})
+    return cells
+
+
+def assess(
+    simulation: Mapping[str, Any],
+    objective: Mapping[str, Any],
+    *,
+    meter: BudgetMeter,
+    round_no: int,
+    seed: int,
+    cell_scorer: Callable[[Mapping[str, Any]], Mapping[str, Any]],
+    parent_report_hash: Optional[str] = None,
+    repeats: int = 1,
+    coverage_source: str = "declared",
+) -> dict:
+    """Run the battery. ``cell_scorer(cell) -> {scalar, verdict, evidence_class}``
+    is the per-cell episode evaluator (injected for determinism/testing; in
+    production it derives + runs a run manifest). Each scored episode charges the
+    meter."""
+    cells = _grid_cells(simulation)
+    verdicts: List[dict] = []
+    calibration_mass_by_cell: Dict[str, float] = {}
+    for cell in cells:
+        for _ in range(max(1, int(repeats))):
+            meter.charge("assess", 1)
+            scored = cell_scorer(cell)
+            row = _loss.verdict_row(
+                eval_ref=scored.get("eval", "agent_report"),
+                cell=cell,
+                scalar=float(scored.get("scalar", 0.0)),
+                verdict=str(scored.get("verdict", "pass")),
+                evidence_class=str(scored.get("evidence_class", "local_gate")),
+                fidelity_admissible=bool(scored.get("fidelity_admissible", True)),
+                provenance={"round": round_no, "seed": seed},
+            )
+            verdicts.append(row)
+            if row["verdict"] == "unstable":
+                key = _loss._cell_key(cell)
+                calibration_mass_by_cell[key] = round(
+                    calibration_mass_by_cell.get(key, 0.0) + 1.0, 6
+                )
+
+    loss_report = _loss.loss_report(objective, verdicts, budget_consumed=meter.consumed)
+    report = {
+        "kind": AGENT_LEARNING_PRACTICE_REPORT_KIND,
+        "round": int(round_no),
+        "objective_version": objective.get("version"),
+        "loss_report": loss_report,
+        "grid": {
+            "cells_total": len(cells),
+            "cells_assessed": len(cells),
+            "coverage_source": coverage_source,
+        },
+        "calibration_mass_by_cell": calibration_mass_by_cell,
+        "budget_consumed": meter.consumed,
+        "seed": int(seed),
+        "parent": parent_report_hash,
+    }
+    return public_payload(report, kind=AGENT_LEARNING_PRACTICE_REPORT_KIND)
+
+
+def practice_report(*args: Any, **kwargs: Any) -> dict:
+    """Public alias for the ASSESS report builder (facade export)."""
+    return assess(*args, **kwargs)

fi/alk/practice/_budget.py

@@ -0,0 +1,81 @@
+"""Unit 8 (BBG U8 / ARCH §2d, AD-I) — the single budget meter.
+
+ONE unit = one scored episode evaluation. Every assess row, ZPD repeat,
+scaffolded/unscaffolded drill evaluation, inner-operator evaluation, scheduled
+review row, and promotion-sweep row charges THIS meter — there is no second
+currency. Soft per-phase enforcement of budget_plan with carry-over.
+"""
+from __future__ import annotations
+
+from typing import Dict
+
+from ._contract import BUDGET_PLAN, PRACTICE_PHASES
+
+# Map the 4-fraction budget_plan onto phases. assess / drill / update / review;
+# diagnose+consolidate+calibrate draw from their adjacent phase allocations.
+_BUDGET_PLAN_PHASES = ("assess", "drill", "update", "review")
+
+
+class BudgetExhausted(RuntimeError):
+    """Raised when the meter has no remaining budget (trainer stop)."""
+
+
+class BudgetMeter:
+    """The single eval-unit meter (AD-I)."""
+
+    def __init__(self, total: int, *, budget_plan: tuple[float, ...] = BUDGET_PLAN) -> None:
+        if not isinstance(total, int) or isinstance(total, bool) or total < 1:
+            raise ValueError("budget total must be an int >= 1")
+        self.total = int(total)
+        self.consumed = 0
+        self._by_phase: Dict[str, int] = {}
+        self._plan = tuple(budget_plan)
+        # per-phase soft caps (allocation of total) keyed by the 4 plan phases.
+        self._caps = {
+            phase: int(round(self.total * frac))
+            for phase, frac in zip(_BUDGET_PLAN_PHASES, self._plan)
+        }
+
+    def _plan_phase(self, phase: str) -> str:
+        if phase in _BUDGET_PLAN_PHASES:
+            return phase
+        if phase == "diagnose":
+            return "assess"
+        if phase in ("consolidate", "calibrate"):
+            return "update"
+        return "drill"
+
+    def charge(self, phase: str, n: int = 1) -> int:
+        if phase not in PRACTICE_PHASES and phase not in ("review", "promotion_sweep"):
+            raise ValueError(f"unknown budget phase {phase!r}")
+        if n < 0:
+            raise ValueError("charge n must be >= 0")
+        if self.consumed + n > self.total:
+            raise BudgetExhausted(
+                f"budget exhausted: consumed={self.consumed} + {n} > total={self.total}"
+            )
+        self.consumed += n
+        self._by_phase[phase] = self._by_phase.get(phase, 0) + n
+        return self.consumed
+
+    def remaining(self) -> int:
+        return self.total - self.consumed
+
+    def slice(self, phase: str, fraction: float) -> int:
+        """Return an integer sub-budget handed to inner operators (their declared
+        eval_budget IS the slice). Bounded by remaining budget."""
+        if not 0.0 <= fraction <= 1.0:
+            raise ValueError("slice fraction must be in [0, 1]")
+        want = int(self.total * fraction)
+        return max(0, min(want, self.remaining()))
+
+    def ledger(self) -> dict:
+        """Per-phase consumption; conservation: sum(phase) == consumed <= total."""
+        by_phase = {p: self._by_phase.get(p, 0) for p in sorted(self._by_phase)}
+        assert sum(by_phase.values()) == self.consumed <= self.total
+        return {
+            "total": self.total,
+            "consumed": self.consumed,
+            "remaining": self.remaining(),
+            "by_phase": by_phase,
+        }

fi/alk/practice/_calibrate.py

@@ -0,0 +1,69 @@
+"""Unit 13 (BBG U13 / ARCH §2d phase 6) — CALIBRATE: the learned-gate.
+
+Per cell: learned iff score ≥ floor AND fork-entropy ≤ threshold AND ICC ≥ floor
+over k; high-score/high-entropy = fluent_not_learned (stays in rotation);
+plateaued/zpd_exited stop rules. Trajectory profiles are post-hoc, never a stop
+rule. Emits ``agent-learning.practice-calibration.v1``.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Sequence
+
+from .._schema import public_payload
+from ..live._contract import UNSTABLE_ICC_FLOOR
+from ._contract import AGENT_LEARNING_PRACTICE_CALIBRATION_KIND, CALIBRATION_VERDICTS
+
+
+def calibrate_cell(
+    cell: Mapping[str, Any],
+    *,
+    score: float,
+    fork_entropy: float,
+    divergence_step: Optional[int],
+    icc: float,
+    repeats: int,
+    score_floor: float = 0.7,
+    entropy_threshold: float = 0.3,
+    icc_floor: float = UNSTABLE_ICC_FLOOR,
+    prior_score: Optional[float] = None,
+    in_band: bool = True,
+) -> dict:
+    """Compute one cell's calibration verdict (synthesis §4(6))."""
+    learned = score >= score_floor and fork_entropy <= entropy_threshold and icc >= icc_floor
+    if learned:
+        verdict = "learned"
+        stop_reason = "learned"
+    elif score >= score_floor and fork_entropy > entropy_threshold:
+        verdict = "fluent_not_learned"  # high-score / high-entropy
+        stop_reason = None
+    elif not in_band:
+        verdict = "zpd_exited"
+        stop_reason = "zpd_exited"
+    elif prior_score is not None and abs(score - prior_score) < 1e-3:
+        verdict = "plateaued"
+        stop_reason = "plateaued"
+    else:
+        verdict = "in_rotation"
+        stop_reason = None
+    assert verdict in CALIBRATION_VERDICTS
+    return {
+        "cell": dict(cell),
+        "score": round(float(score), 6),
+        "fork_entropy": round(float(fork_entropy), 6),
+        "divergence_step": divergence_step,
+        "icc": round(float(icc), 6),
+        "repeats": int(repeats),
+        "verdict": verdict,
+        "stop_reason": stop_reason,
+    }
+
+
+def calibrate(cells: Sequence[Mapping[str, Any]], *, round_no: int) -> dict:
+    """Emit the calibration artifact over a list of pre-computed cell measures."""
+    records = [calibrate_cell(**c) if "verdict" not in c else dict(c) for c in cells]
+    report = {
+        "kind": AGENT_LEARNING_PRACTICE_CALIBRATION_KIND,
+        "round": int(round_no),
+        "cells": records,
+    }
+    return public_payload(report, kind=AGENT_LEARNING_PRACTICE_CALIBRATION_KIND)

fi/alk/practice/_capstone.py

@@ -0,0 +1,86 @@
+"""Unit 22 (BBG U22 / RU-7) — the capstone A/B harness.
+
+An EXPERIMENT, not a release gate (gates stay deterministic; nothing here
+registers a check). The harness runs the practice loop vs real search backends
+at EQUAL TOTAL metered budget (the one meter, AD-I) over kit-local fixtures, and
+REFUSES to print a headline unless every arm completed the same declared total
+(``headline: null`` + ``ab_budget_mismatch`` otherwise — doctrine #11).
+
+This module builds the harness so it CAN run offline-deterministically; running
+the capstone experiment + writing the paper is a separate later task.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import List
+
+from .._schema import public_payload
+from ._contract import AGENT_LEARNING_PRACTICE_LOOP_KIND
+
+# RU-7: real backend tokens only (the canon tuple stays closed). "greedy" = bandit.
+CAPSTONE_ARMS = ("practice_loop", "gepa", "tpe", "society", "bandit")
+# manifest-level ablation knobs of the practice arm (never a code fork).
+CAPSTONE_ABLATIONS = ("a1_no_zpd", "a2_no_spacing", "a3_no_consolidation", "a4_no_calibration")
+
+
+def _load_config(manifest_dir: Path) -> dict:
+    config_path = manifest_dir / "capstone.json"
+    if not config_path.exists():
+        raise FileNotFoundError(f"capstone config not found at {config_path}")
+    return json.loads(config_path.read_text())
+
+
+def run_ab(manifest_dir: str | Path) -> dict:
+    """Run the A/B harness. Reads ``capstone.json`` declaring the arms and the
+    equal total budget; enforces the equal-budget headline rule (doctrine #11).
+
+    The arm execution is offline-deterministic: each arm reports its declared
+    total metered budget and a (placeholder until the experiment runs)
+    retention_after_interference. Running the experiment itself is a later task;
+    this harness validates the equal-budget contract and emits the ab_harness
+    block."""
+    manifest_dir = Path(manifest_dir)
+    config = _load_config(manifest_dir)
+    declared_total = int(config.get("eval_budget", 0))
+    arms_decl = config.get("arms") or list(CAPSTONE_ARMS)
+
+    arms: List[dict] = []
+    budgets: set[int] = set()
+    for arm in arms_decl:
+        arm_total = int(config.get("arm_budgets", {}).get(arm, declared_total))
+        budgets.add(arm_total)
+        arms.append({
+            "arm": arm,
+            "total_metered_budget": arm_total,
+            # best_found is printed per arm precisely so a search arm may visibly
+            # win best-found while losing retention (the headline).
+            "best_found": None,
+            "retention_after_interference": None,
+        })
+
+    # equal TOTAL metered budget per arm (AD-I) — else headline null + warning.
+    budget_match = len(budgets) == 1 and declared_total in budgets
+    findings: List[dict] = []
+    headline = None
+    if not budget_match:
+        findings.append({
+            "type": "ab_budget_mismatch", "level": "warning",
+            "reason": f"arms did not complete the same declared total ({sorted(budgets)} != {declared_total})",
+        })
+    else:
+        headline = {"metric": "retention_after_interference", "by_arm": None,
+                    "note": "populated when the experiment runs (a later task)"}
+
+    payload = {
+        "kind": AGENT_LEARNING_PRACTICE_LOOP_KIND,
+        "ab_harness": {
+            "arms": arms,
+            "ablations": list(CAPSTONE_ABLATIONS),
+            "equal_total_budget": declared_total,
+            "budget_match": budget_match,
+            "headline": headline,
+            "findings": findings,
+        },
+    }
+    return public_payload(payload, kind=AGENT_LEARNING_PRACTICE_LOOP_KIND)["ab_harness"]

fi/alk/practice/_contract.py

@@ -0,0 +1,91 @@
+"""Unit 8 (BBG U8 / ARCH §3) — practice vocabularies + canon constants.
+
+Every constant ARCH §3 freezes for the Practice Loop, verbatim. RU-1 numeric
+defaults. Evidence/verdict vocab is IMPORTED from live/_contract.py, never
+redeclared (ARCH §1.7). The Unit-20 gate byte-compares these.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from ..live._contract import (  # noqa: F401 (re-exported canon)
+    DEFAULT_REPEATS,
+    EVIDENCE_CLASSES,
+    RELEASE_ADMISSIBLE_EVIDENCE_CLASSES,
+    UNSTABLE_ICC_FLOOR,
+    VERDICTS,
+)
+from ..loss import (  # noqa: F401 (re-export the objective/loss-report kinds)
+    AGENT_LEARNING_LOSS_REPORT_KIND,
+    AGENT_LEARNING_OBJECTIVE_KIND,
+)
+
+# --- artifact kinds (RU-4) -------------------------------------------------
+AGENT_LEARNING_PRACTICE_LOOP_KIND = "agent-learning.practice-loop.v1"
+AGENT_LEARNING_PRACTICE_RESULT_KIND = "agent-learning.practice-result.v1"
+AGENT_LEARNING_PRACTICE_REPORT_KIND = "agent-learning.practice-report.v1"
+AGENT_LEARNING_PRACTICE_DEFICITS_KIND = "agent-learning.practice-deficits.v1"
+AGENT_LEARNING_PRACTICE_DRILL_KIND = "agent-learning.practice-drill.v1"
+AGENT_LEARNING_PRACTICE_UPDATE_KIND = "agent-learning.practice-update.v1"
+AGENT_LEARNING_CONSOLIDATED_LESSON_KIND = "agent-learning.consolidated-lesson.v1"
+AGENT_LEARNING_PRACTICE_CALIBRATION_KIND = "agent-learning.practice-calibration.v1"
+
+PRACTICE_ARTIFACT_KINDS = (
+    AGENT_LEARNING_PRACTICE_LOOP_KIND,
+    AGENT_LEARNING_PRACTICE_RESULT_KIND,
+    AGENT_LEARNING_PRACTICE_REPORT_KIND,
+    AGENT_LEARNING_PRACTICE_DEFICITS_KIND,
+    AGENT_LEARNING_PRACTICE_DRILL_KIND,
+    AGENT_LEARNING_PRACTICE_UPDATE_KIND,
+    AGENT_LEARNING_CONSOLIDATED_LESSON_KIND,
+    AGENT_LEARNING_PRACTICE_CALIBRATION_KIND,
+)
+
+# --- phases + vocabularies (ARCH §3) ---------------------------------------
+PRACTICE_PHASES = ("assess", "diagnose", "drill", "update", "consolidate", "calibrate")
+SCAFFOLD_TYPES = ("world_simplification", "hint_tool", "worked_example", "relaxed_success")
+ZPD_VERDICTS = ("in_band", "vygotsky_form", "below_band", "above_band", "unstable")
+CALIBRATION_VERDICTS = ("learned", "fluent_not_learned", "in_rotation", "plateaued", "zpd_exited")
+LADDER_STATES = ("episodic", "instruction", "skill")
+PRACTICE_REPLAY_INTERVALS = (1, 2, 4, 8, 16)  # cap 16
+STORE_STATUSES = ("active", "retired")
+RETIREMENT_REASONS = ("repeated_failure", "obsolete")
+LESSON_KINDS = ("instruction_block", "config_patch", "skill")
+
+# --- 13D-5 capstone ablation knobs (additive; the experiment path only) -----
+# Real trainer config flags that change run_practice_loop behaviour (never
+# labels): A1 disables ZPD filtering, A2 disables standing spaced reviews
+# (replay only at promotion), A3 skips the consolidate phase entirely, A4
+# disables the calibration learned-gate (fixed-k, never stop early).
+PRACTICE_ABLATIONS = ("a1_no_zpd", "a2_no_spacing", "a3_no_consolidation", "a4_no_calibration")
+
+# --- RU-1 defaults ---------------------------------------------------------
+ZPD_BAND = (0.2, 0.7)
+REVIEW_RATIO = 0.25
+BUDGET_PLAN = (0.25, 0.35, 0.25, 0.15)  # assess / drill / update / review
+PRACTICE_STORE_ACTIVE_CAP = 64
+SCAFFOLD_FADE_DEFAULT = (1.0, 0.5, 0.0)  # MUST end at 0.0
+MAX_REPLAY_INTERVAL = 16
+DEFAULT_MAX_ROUNDS = 8
+DEFAULT_INNER_OPERATOR_BACKEND = "society"
+
+# --- store placement (AD-G — the Phase-8 ledger precedent) -----------------
+LESSON_ID_PREFIX = "lesson_"
+PRACTICE_STORE_PATH_ENV = "AGENT_LEARNING_PRACTICE_STORE_PATH"
+PRACTICE_STORE_HOME_ENV = "AGENT_LEARNING_HOME"
+PRACTICE_STORE_DIR_NAME = "practice"
+PRACTICE_STORE_FILE_NAME = "records.jsonl"
+
+
+def practice_store_path(override: str | Path | None = None) -> Path:
+    """Resolve the consolidation store path (AD-G). Precedence: explicit arg >
+    AGENT_LEARNING_PRACTICE_STORE_PATH > ${AGENT_LEARNING_HOME:-~/.agent-learning}
+    /practice/records.jsonl."""
+    if override is not None:
+        return Path(override)
+    env_override = os.environ.get(PRACTICE_STORE_PATH_ENV)
+    if env_override:
+        return Path(env_override)
+    home = os.environ.get(PRACTICE_STORE_HOME_ENV) or (Path.home() / ".agent-learning")
+    return Path(home) / PRACTICE_STORE_DIR_NAME / PRACTICE_STORE_FILE_NAME

fi/alk/practice/_diagnose.py

@@ -0,0 +1,79 @@
+"""Unit 10 (BBG U10 / ARCH §2d phase 2) — DIAGNOSE: pure composition.
+
+Ranks weak cells, attributes each to a harness_layer ∈ HARNESS_LAYERS via
+ComponentDiagnosis and relevant_search_paths (narrowing, never widening). Credit
+method "layer_scoped" always; "counterfactual_replay" (13C T7) only budget-
+permitting (fallback = layer scoping only). Emits
+``agent-learning.practice-deficits.v1`` ranked deterministically (loss desc,
+tie-break by cell content hash). No new machinery.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, List, Mapping, Optional
+
+from .._schema import public_payload
+from ._contract import AGENT_LEARNING_PRACTICE_DEFICITS_KIND
+
+
+def _components():
+    import importlib
+    return importlib.import_module("fi.opt.components")
+
+
+def _cell_hash(cell: Mapping[str, Any]) -> str:
+    return json.dumps(cell, sort_keys=True, default=str)
+
+
+def diagnose(
+    practice_report: Mapping[str, Any],
+    *,
+    search_space: Mapping[str, Any],
+    layer_hint: Optional[Mapping[str, str]] = None,
+    allow_counterfactual: bool = False,
+) -> dict:
+    """Pure composition over the ASSESS report's loss cells. ``layer_hint`` maps a
+    cell key → harness_layer (from upstream diagnosis); default 'execution'."""
+    components = _components()
+    harness_layers = components.HARNESS_LAYERS
+    prefixes = components.HARNESS_LAYER_PATH_PREFIXES
+    layer_hint = dict(layer_hint or {})
+
+    loss_report = practice_report.get("loss_report") or {}
+    cells = loss_report.get("cells") or []
+    # rank weak cells: loss desc, tie-break by cell content hash.
+    ranked = sorted(
+        cells,
+        key=lambda c: (-float(c.get("loss", 0.0)), _cell_hash(c.get("cell") or {})),
+    )
+
+    deficits: List[dict] = []
+    for cell_report in ranked:
+        cell = cell_report.get("cell") or {}
+        if float(cell_report.get("loss", 0.0)) <= 0.0:
+            continue  # closed cells are not deficits
+        layer = layer_hint.get(_cell_hash(cell), "execution")
+        if layer not in harness_layers:
+            layer = "execution"
+        # narrowing search paths from the layer's prefixes.
+        layer_prefixes = prefixes.get(layer, ())
+        narrowed = sorted(
+            path for path in search_space
+            if any(path == p or path.startswith(f"{p}.") for p in layer_prefixes)
+        )
+        method = "counterfactual_replay" if allow_counterfactual else "layer_scoped"
+        deficits.append({
+            "cell": cell,
+            "harness_layer": layer,
+            "search_paths": narrowed,
+            "credit": {"method": method, "rows": []},
+            "evidence_rows": cell_report.get("verdicts") or [],
+        })
+
+    report = {
+        "kind": AGENT_LEARNING_PRACTICE_DEFICITS_KIND,
+        "round": practice_report.get("round"),
+        "objective_version": practice_report.get("objective_version"),
+        "deficits": deficits,
+    }
+    return public_payload(report, kind=AGENT_LEARNING_PRACTICE_DEFICITS_KIND)