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

fi/alk/practice/_schedule.py

@@ -0,0 +1,102 @@
+"""Unit 9 (BBG U9 / ARCH §2d) — the spaced-replay schedule state machine.
+
+The T1-T7 transition table as a PURE function. Public surface: ``due_reviews``
+ONLY. This module has NO code path into promotion (the update module is the only
+promotion invoker, obtaining rows exclusively from the store's deck union) — the
+13D-D7 boundary is structural, not disciplinary. There is deliberately NO import
+of the promotion invoker here.
+"""
+from __future__ import annotations
+
+from typing import Any, List, Mapping
+
+from ._contract import MAX_REPLAY_INTERVAL
+from ._store import demote_ladder
+
+_LADDER_ORDER = ("episodic", "instruction", "skill")
+
+
+def _append_history(record: dict, round_no: int, event: str, outcome: str) -> None:
+    history = list(record.get("history") or [])
+    history.append({"round": int(round_no), "event": str(event), "outcome": str(outcome)})
+    record["history"] = history
+
+
+def transition(record: Mapping[str, Any], event: str, round_no: int) -> dict:
+    """The T1-T7 table. ``event`` ∈ {'review_pass', 'review_fail', 'obsolete'}.
+    Returns a NEW record snapshot (every transition appends to history)."""
+    out = dict(record)
+    out["schedule"] = dict(out.get("schedule") or {})
+    schedule = out["schedule"]
+    ladder = out.get("ladder_state", "episodic")
+
+    if schedule.get("status") == "retired":
+        # T7: retired is terminal.
+        _append_history(out, round_no, event, "terminal_retired")
+        return out
+
+    if event == "obsolete":
+        # T5: obsolescence ⇒ retired "obsolete".
+        schedule["status"] = "retired"
+        schedule["retired_reason"] = "obsolete"
+        _append_history(out, round_no, "obsolete", "retired")
+        return out
+
+    if event == "review_pass":
+        # T1: interval ← min(2·i, 16); due ← round+interval; failures ← 0.
+        interval = int(schedule.get("interval_rounds", 1))
+        new_interval = min(2 * interval, MAX_REPLAY_INTERVAL)
+        schedule["interval_rounds"] = new_interval
+        schedule["due_round"] = int(round_no) + new_interval
+        schedule["consecutive_failures"] = 0
+        _append_history(out, round_no, "review_pass", f"interval->{new_interval}")
+        return out
+
+    if event == "review_fail":
+        failures = int(schedule.get("consecutive_failures", 0)) + 1
+        schedule["consecutive_failures"] = failures
+        if failures >= 2:
+            # T4: failures ≥ 2 ⇒ retired "repeated_failure".
+            schedule["status"] = "retired"
+            schedule["retired_reason"] = "repeated_failure"
+            _append_history(out, round_no, "review_fail", "retired_repeated_failure")
+            return out
+        if ladder == "episodic":
+            # T3: fail at episodic ⇒ retired "repeated_failure" (no rung below).
+            schedule["status"] = "retired"
+            schedule["retired_reason"] = "repeated_failure"
+            _append_history(out, round_no, "review_fail", "retired_episodic_fail")
+            return out
+        # T2: fail above episodic ⇒ demote one rung; interval←1; due←round+1.
+        demoted = demote_ladder(out)
+        out["ladder_state"] = demoted["ladder_state"]
+        schedule["interval_rounds"] = 1
+        schedule["due_round"] = int(round_no) + 1
+        _append_history(out, round_no, "review_fail", f"demote->{out['ladder_state']}")
+        return out
+
+    raise ValueError(f"unknown schedule event {event!r}")
+
+
+def due_reviews(records: List[Mapping[str, Any]], round_no: int) -> List[dict]:
+    """Select due active records, sorted by (due_round, record_id) — deterministic
+    tie-break by content id. The ONLY public path from this module."""
+    due = [
+        dict(r)
+        for r in records
+        if r.get("schedule", {}).get("status") == "active"
+        and int(r.get("schedule", {}).get("due_round", 0)) <= int(round_no)
+    ]
+    due.sort(key=lambda r: (int(r["schedule"]["due_round"]), str(r.get("record_id", ""))))
+    return due
+
+
+def mark_obsolete_if_path_left_space(
+    record: Mapping[str, Any], search_paths: List[str], round_no: int
+) -> dict:
+    """T5 obsolescence trigger helper: a deck row's config path leaves the search
+    space ⇒ retire 'obsolete'. (Caller supplies the current search space.)"""
+    applies = record.get("lesson", {}).get("applies_to_paths") or []
+    if applies and not any(p in set(search_paths) for p in applies):
+        return transition(record, "obsolete", round_no)
+    return dict(record)

fi/alk/practice/_store.py

@@ -0,0 +1,194 @@
+"""Unit 9 (BBG U9 / ARCH §2d) — the consolidation store.
+
+Consolidated records (decks ARE frozen rows, AD-D): record ids use the
+optimizer-space frozen-row idiom (``lesson_`` + 16-hex sorted-JSON digest).
+Append-only JSONL (AD-G); state transitions are appended full-record snapshots
+(latest-wins on read). ``full_deck()`` is the ONLY promotion-row source (13D-D7)
+— the FULL union of all P4 frozen rows + every active record's complete deck,
+regardless of schedule state. Cap admission REFUSES at active_cap (AD-H), never
+evicts.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional
+
+from ._contract import (
+    LADDER_STATES,
+    LESSON_ID_PREFIX,
+    LESSON_KINDS,
+    PRACTICE_REPLAY_INTERVALS,
+    PRACTICE_STORE_ACTIVE_CAP,
+    practice_store_path,
+)
+
+# fields that do NOT enter the record id (envelope/mutable state).
+_NON_ID_FIELDS = {"record_id", "schedule", "history"}
+
+
+def _sorted_json_digest(payload: Any) -> str:
+    return hashlib.sha256(
+        json.dumps(payload, sort_keys=True, default=str).encode("utf-8")
+    ).hexdigest()
+
+
+def record_id(body: Mapping[str, Any]) -> str:
+    """The frozen-row idiom: lesson_ + 16-hex sorted-JSON digest over all
+    non-envelope fields (recipe-agreement with _expected_frozen_row_id)."""
+    payload = {k: v for k, v in body.items() if k not in _NON_ID_FIELDS}
+    return LESSON_ID_PREFIX + _sorted_json_digest(payload)[:16]
+
+
+def build_record(
+    *,
+    lesson: Mapping[str, Any],
+    source_justification: Mapping[str, Any],
+    deck: List[str],
+    cells: List[Any],
+    created_round: int,
+    seed: int,
+    interval_rounds: int = 1,
+    due_round: Optional[int] = None,
+    provenance: Optional[Mapping[str, Any]] = None,
+    ladder_state: str = "episodic",
+) -> dict:
+    """Construct a consolidated record (ARCH §2d schema verbatim)."""
+    if ladder_state not in LADDER_STATES:
+        raise ValueError(f"ladder_state {ladder_state!r} not in {LADDER_STATES}")
+    if lesson.get("kind") not in LESSON_KINDS:
+        raise ValueError(f"lesson.kind {lesson.get('kind')!r} not in {LESSON_KINDS}")
+    if interval_rounds not in PRACTICE_REPLAY_INTERVALS:
+        raise ValueError(f"interval_rounds {interval_rounds!r} not in {PRACTICE_REPLAY_INTERVALS}")
+    body = {
+        "kind": "agent-learning.consolidated-lesson.v1",
+        "ladder_state": ladder_state,
+        "lesson": {
+            "kind": lesson["kind"],
+            "payload": lesson.get("payload"),
+            "applies_to_paths": list(lesson.get("applies_to_paths") or []),
+        },
+        "source_justification": dict(source_justification),
+        "deck": sorted(set(deck)),
+        "schedule": {
+            "interval_rounds": int(interval_rounds),
+            "due_round": int(due_round if due_round is not None else created_round + interval_rounds),
+            "consecutive_failures": 0,
+            "status": "active",
+            "retired_reason": None,
+        },
+        "cells": list(cells),
+        "history": [],
+        "created_round": int(created_round),
+        "seed": int(seed),
+        "provenance": dict(provenance or {}),
+    }
+    body["record_id"] = record_id(body)
+    return body
+
+
+class ConsolidationStore:
+    """Append-only JSONL store under the user-owned home (AD-G)."""
+
+    def __init__(self, path: str | Path | None = None, *, active_cap: int = PRACTICE_STORE_ACTIVE_CAP) -> None:
+        self.path = practice_store_path(path)
+        self.active_cap = int(active_cap)
+
+    # --- IO (tolerant reader, AD-G) ----------------------------------------
+    def _read_snapshots(self) -> List[dict]:
+        if not self.path.exists():
+            return []
+        out: List[dict] = []
+        for line in self.path.read_text().splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue  # tolerant reader (live/_transcript.py philosophy)
+        return out
+
+    def _append(self, record: Mapping[str, Any]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a") as handle:
+            handle.write(json.dumps(record, sort_keys=True, default=str) + "\n")
+
+    def latest(self) -> Dict[str, dict]:
+        """Latest-wins by record_id over the append-only snapshots."""
+        out: Dict[str, dict] = {}
+        for snapshot in self._read_snapshots():
+            rid = snapshot.get("record_id")
+            if rid:
+                out[rid] = snapshot
+        return out
+
+    def active_records(self) -> List[dict]:
+        return [r for r in self.latest().values() if r.get("schedule", {}).get("status") == "active"]
+
+    # --- admission (cap refusal, AD-H) -------------------------------------
+    def admit(self, record: Mapping[str, Any]) -> dict:
+        """Admit a record, or refuse with cap_deferred at active_cap (refusal
+        over eviction — T6/AD-H)."""
+        rid = record.get("record_id") or record_id(record)
+        existing = self.latest()
+        if rid in existing:
+            self._append(dict(record))
+            return {"admitted": True, "record_id": rid, "reason": "updated"}
+        active_count = len([r for r in existing.values()
+                            if r.get("schedule", {}).get("status") == "active"])
+        if active_count >= self.active_cap:
+            return {
+                "admitted": False,
+                "record_id": rid,
+                "status": "cap_deferred",
+                "reason": (
+                    f"consolidation store at active_cap={self.active_cap}; admission "
+                    "REFUSED (a slot frees only via retirement — refusal over eviction)"
+                ),
+            }
+        self._append(dict(record))
+        return {"admitted": True, "record_id": rid, "reason": "admitted"}
+
+    def update_record(self, record: Mapping[str, Any]) -> None:
+        """Append a full-record snapshot (state transition, never a rewrite)."""
+        self._append(dict(record))
+
+    # --- the ONLY promotion-row source (13D-D7) ----------------------------
+    def full_deck(self, *, frozen_rows: Optional[List[str]] = None) -> List[str]:
+        """The UNION of all P4 frozen rows + every active record's complete deck,
+        REGARDLESS of any record's schedule state. This is the 13D-D7 boundary."""
+        rows: set[str] = set(frozen_rows or [])
+        for record in self.active_records():
+            rows.update(record.get("deck") or [])
+        return sorted(rows)
+
+
+def ladder_state(record: Mapping[str, Any]) -> str:
+    """Read the stored ladder state (never recomputed from history, AD-H)."""
+    return str(record.get("ladder_state") or "episodic")
+
+
+# --- ladder transitions (up; ARCH §2d promotion ladder) --------------------
+_LADDER_ORDER = ("episodic", "instruction", "skill")
+
+
+def promote_ladder(record: Mapping[str, Any]) -> dict:
+    """Move one rung up (episodic→instruction→skill)."""
+    out = dict(record)
+    current = out.get("ladder_state", "episodic")
+    idx = _LADDER_ORDER.index(current)
+    if idx < len(_LADDER_ORDER) - 1:
+        out["ladder_state"] = _LADDER_ORDER[idx + 1]
+    return out
+
+
+def demote_ladder(record: Mapping[str, Any]) -> dict:
+    """Move one rung down (skill→instruction→episodic)."""
+    out = dict(record)
+    current = out.get("ladder_state", "episodic")
+    idx = _LADDER_ORDER.index(current)
+    if idx > 0:
+        out["ladder_state"] = _LADDER_ORDER[idx - 1]
+    return out

fi/alk/practice/_trainer.py

@@ -0,0 +1,245 @@
+"""Unit 13 (BBG U13 / ARCH §2d phases 5-6) — the six-phase practice driver.
+
+``run_practice_loop(manifest) -> dict``: the outer loop per round —
+rank deficits → drill (interleaved with due reviews at review_ratio, reviews
+ONLY between promotions) → update → consolidate → re-assess; bounded by
+max_rounds and the meter. Entry-point checks (before ANY budget): derived-
+objective refusal (AD-F), eval_budget presence, extension admission. Determinism
+per ARCH §2d (all child seeds derived; every artifact carries seed + parent
+hashes). Emits ``agent-learning.practice-result.v1`` through public_payload, so
+every episode lands a telemetry ledger row with zero new telemetry code.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Callable, List, Mapping, Optional
+
+from .._schema import public_payload
+from .. import loss as _loss
+from . import _assess, _diagnose, _drill, _schedule, _store, _update
+from ._budget import BudgetExhausted, BudgetMeter
+from ._contract import (
+    AGENT_LEARNING_PRACTICE_RESULT_KIND,
+    BUDGET_PLAN,
+    DEFAULT_INNER_OPERATOR_BACKEND,
+    DEFAULT_MAX_ROUNDS,
+    PRACTICE_ABLATIONS,
+    REVIEW_RATIO,
+    SCAFFOLD_FADE_DEFAULT,
+    ZPD_BAND,
+)
+
+
+def _hash(payload: Mapping[str, Any]) -> str:
+    return "sha256:" + hashlib.sha256(
+        json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str).encode("utf-8")
+    ).hexdigest()
+
+
+class PracticeRefusal(ValueError):
+    """Raised at the entry point before any budget is spent."""
+
+
+def run_practice_loop(
+    manifest: Mapping[str, Any],
+    *,
+    cell_scorer: Optional[Callable[[Mapping[str, Any]], Mapping[str, Any]]] = None,
+    repeat_scorer: Optional[Callable[[Mapping[str, Any], int], float]] = None,
+    replay_row: Optional[Callable[[str], bool]] = None,
+    store: Optional[_store.ConsolidationStore] = None,
+    extension_admission_check: Optional[Callable[[], Optional[dict]]] = None,
+) -> dict:
+    """Run the practice loop deterministically. Scorers are injected so the gate
+    and capstone run offline; production wires them to the simulation engine."""
+    practice = dict(manifest.get("practice") or manifest)
+    sim_block = dict(practice.get("simulation") or {})
+    simulation = dict(sim_block.get("inline") or {})
+    objective = simulation.get("objective")
+
+    # --- entry-point refusals (BEFORE any budget) --------------------------
+    # 1. derived-objective refusal (AD-F).
+    _loss.refuse_derived_for_training(objective)
+    # 2. eval_budget presence (else budget_undeclared).
+    eval_budget = practice.get("eval_budget")
+    if not isinstance(eval_budget, int) or isinstance(eval_budget, bool) or eval_budget < 1:
+        raise PracticeRefusal("budget_undeclared: eval_budget is required and must be an int >= 1")
+    # 3. extension admission for the inner operator (before any phase spends).
+    if extension_admission_check is not None:
+        refusal = extension_admission_check()
+        if refusal is not None and not refusal.get("admitted", True):
+            raise PracticeRefusal(
+                f"extension_evidence_inadmissible: {refusal.get('reason')}"
+            )
+
+    seed = practice.get("seed")
+    if seed is None:
+        raise PracticeRefusal("seed is required (declared-MANDATORY pair: eval_budget + seed)")
+    seed = int(seed)
+
+    max_rounds = int(practice.get("max_rounds", DEFAULT_MAX_ROUNDS))
+    budget_plan = tuple(practice.get("budget_plan") or BUDGET_PLAN)
+    review_ratio = float(practice.get("review_ratio", REVIEW_RATIO))
+    zpd = dict(practice.get("zpd") or {})
+    band = tuple(zpd.get("band") or ZPD_BAND)
+    k = int(zpd.get("k", 8))
+    icc_floor = float(zpd.get("icc_floor", 0.5))
+    scaffold_fade = dict(practice.get("scaffold_fade") or {})
+    fade = tuple(scaffold_fade.get("intensities") or SCAFFOLD_FADE_DEFAULT)
+    inner_operator = dict(practice.get("inner_operator") or {})
+    operator_backend = str(inner_operator.get("backend", DEFAULT_INNER_OPERATOR_BACKEND))
+    frozen_rows = list(practice.get("frozen_rows") or [])
+    search_space = dict(practice.get("search_space") or manifest.get("search_space") or {})
+
+    # --- ablation knobs (13D-5 capstone; additive, default = full loop) -----
+    # Real config flags that change behaviour, never labels. Unknown tokens are
+    # a contract error (the experiment must not silently no-op an ablation).
+    ablations = tuple(practice.get("ablations") or ())
+    for ablation in ablations:
+        if ablation not in PRACTICE_ABLATIONS:
+            raise PracticeRefusal(
+                f"unknown ablation {ablation!r}; must be one of {PRACTICE_ABLATIONS}"
+            )
+    a1_no_zpd = "a1_no_zpd" in ablations
+    a2_no_spacing = "a2_no_spacing" in ablations
+    a3_no_consolidation = "a3_no_consolidation" in ablations
+    a4_no_calibration = "a4_no_calibration" in ablations
+    # A4 needs the learned-gate; the loop reports per-cell stop signals so an
+    # external driver (the experiment engine) can stop a learned cell early.
+    learned_cells: set = set()
+    # Equal-total-budget discipline (synthesis §5 / AD-I): every ZPD repeat is a
+    # scored evaluation and MUST charge the meter. Opt-in (default off) so the
+    # gate/determinism-fixture path stays byte-identical; the capstone experiment
+    # turns it on so the practice arm meters the same currency as the search arms.
+    meter_drill_repeats = bool(practice.get("meter_drill_repeats", False))
+
+    meter = BudgetMeter(eval_budget, budget_plan=budget_plan)
+    if store is None:
+        store_knob = dict(practice.get("store") or {})
+        store = _store.ConsolidationStore(store_knob.get("path"),
+                                          active_cap=int(store_knob.get("active_cap", 64)))
+
+    # default deterministic scorers (all-pass) if not injected.
+    cell_scorer = cell_scorer or (lambda cell: {"scalar": 1.0, "verdict": "pass", "evidence_class": "local_gate"})
+    repeat_scorer = repeat_scorer or (lambda sim, s: 1.0)
+    replay_row = replay_row or (lambda row: True)
+
+    rounds: List[dict] = []
+    parent_report_hash: Optional[str] = None
+    stop_reason = "max_rounds"
+
+    try:
+        for round_no in range(max_rounds):
+            # ASSESS
+            report = _assess.assess(
+                simulation, objective, meter=meter, round_no=round_no, seed=seed,
+                cell_scorer=cell_scorer, parent_report_hash=parent_report_hash,
+            )
+            parent_report_hash = _hash(report)
+            # DIAGNOSE
+            deficits = _diagnose.diagnose(report, search_space=search_space)
+            # DRILL (interleaved with due reviews between promotions).
+            # A2 no-spacing: NO standing between-promotion reviews (the deck
+            # only ever replays at the promotion sweep — replay-only-at-promotion).
+            if not a2_no_spacing:
+                due = _schedule.due_reviews(store.active_records(), round_no)
+                review_slots = int(len(deficits["deficits"]) * review_ratio)
+                for review_rec in due[:review_slots]:
+                    meter.charge("review", 1)
+                    review_pass = all(replay_row(r) for r in review_rec.get("deck") or [])
+                    event = "review_pass" if review_pass else "review_fail"
+                    store.update_record(_schedule.transition(review_rec, event, round_no))
+
+            drill_records: List[dict] = []
+            update_records: List[dict] = []
+            for deficit in deficits["deficits"]:
+                # A4 no-calibration: fixed-k, never stop a learned cell early —
+                # so learned cells are NOT pruned and keep consuming drill budget.
+                if not a4_no_calibration and _loss._cell_key(deficit.get("cell") or {}) in learned_cells:
+                    continue
+                # charge the ZPD repeats to the meter (opt-in, AD-I) BEFORE the
+                # drill runs — k repeats per drill are k scored evaluations.
+                if meter_drill_repeats:
+                    meter.charge("drill", k)
+                drill = _drill.drill(
+                    deficit, _drill_simulation(simulation, deficit), seed=seed, round_no=round_no,
+                    repeat_scorer=repeat_scorer, fade_intensities=fade, k=k,
+                    icc_floor=icc_floor, band=band,
+                )
+                drill_records.append(drill)
+                # A1 no-ZPD: drill is NOT ZPD-filtered — an unstable/out-of-band
+                # drill is still promoted to UPDATE (the full loop quarantines it).
+                if not a1_no_zpd and drill["zpd_measurement"]["verdict"] == "unstable":
+                    continue
+                # CALIBRATE (A4 disables): mark a cell learned when its
+                # unscaffolded pass-rate clears the band ceiling at stable ICC.
+                if not a4_no_calibration:
+                    zpd = drill["zpd_measurement"]
+                    if (zpd["unscaffolded_pass_rate"] >= float(band[1])
+                            and zpd["icc"] >= icc_floor):
+                        learned_cells.add(_loss._cell_key(deficit.get("cell") or {}))
+                # UPDATE (the D7 promotion sweep)
+                upd = _update.update(
+                    deficit, allowed_layer=deficit.get("harness_layer", "execution"),
+                    allowed_paths=deficit.get("search_paths") or [],
+                    proposals=[{"patch": {}, "justification": {"hetu": "drill"}}],
+                    store=store, frozen_rows=frozen_rows, replay_row=replay_row,
+                    meter=meter, operator_backend=operator_backend,
+                )
+                update_records.append(upd)
+                # CONSOLIDATE (admit a lesson; cap ⇒ cap_deferred).
+                # A3 no-consolidation: skip the consolidate phase entirely —
+                # lessons stay episodic-in-the-run and are NEVER admitted to the
+                # store, so there is no spaced deck to protect against drift.
+                if not a3_no_consolidation and upd["promotion_sweep"]["all_closed"]:
+                    rec = _store.build_record(
+                        lesson={"kind": "config_patch", "payload": {}, "applies_to_paths": deficit.get("search_paths") or []},
+                        source_justification=upd.get("selected_candidate", {}).get("justification", {}) if upd.get("selected_candidate") else {},
+                        deck=list(frozen_rows), cells=[deficit.get("cell")],
+                        created_round=round_no, seed=seed,
+                    )
+                    store.admit(rec)
+            rounds.append({
+                "round": round_no,
+                "report": report,
+                "deficits": deficits,
+                "drills": drill_records,
+                "updates": update_records,
+            })
+    except BudgetExhausted:
+        stop_reason = "budget_exhausted"
+
+    result = {
+        "kind": AGENT_LEARNING_PRACTICE_RESULT_KIND,
+        "name": practice.get("name") or manifest.get("name"),
+        "seed": seed,
+        "simulation_version": simulation.get("version"),
+        "objective_version": (objective or {}).get("version"),
+        "stop_reason": stop_reason,
+        "rounds_completed": len(rounds),
+        "ablations": list(ablations),
+        "learned_cell_count": len(learned_cells),
+        "budget_ledger": meter.ledger(),
+        "rounds": rounds,
+        # headline — AgentCL stability/plasticity/generalization, never best-found.
+        "retention_and_transfer_at_equal_budget": {
+            "stability": None, "plasticity": None, "generalization": None,
+        },
+        "promotion_veto_boundary": (
+            "all frozen rows replay at every promotion regardless of schedule state (13D-D7)"
+        ),
+        "detection_latency": {"measured": None, "declared_bound": practice.get("schedule", {}).get("detection_latency_bound")},
+    }
+    return public_payload(result, kind=AGENT_LEARNING_PRACTICE_RESULT_KIND)
+
+
+def _drill_simulation(simulation: Mapping[str, Any], deficit: Mapping[str, Any]) -> dict:
+    """A derived Simulation narrowed to the target cell (v1 fallback:
+    studio_perturbation lineage — a copy carrying the deficit coordinate)."""
+    out = dict(simulation)
+    out = {**out, "metadata": {**dict(out.get("metadata") or {}), "drill_cell": deficit.get("cell")}}
+    return out
+
+
+def ladder_state(record: Mapping[str, Any]) -> str:
+    return _store.ladder_state(record)

fi/alk/practice/_update.py

@@ -0,0 +1,125 @@
+"""Unit 12 (BBG U12 / ARCH §2d phase 4) — scoped update + the D7 enforcement point.
+
+Layer locality enforced against HARNESS_LAYER_PATH_PREFIXES; out-of-layer
+proposals are RECORDED (asiddha), never silently allowed/dropped. The inner
+operator runs through optimize_manifest_with_backend_override with a sliced
+budget.
+
+THE 13D-D7 ENFORCEMENT POINT: this is the ONLY module that invokes promotion.
+The promotion sweep replays the store's full deck union — all P4 frozen rows +
+every active record's complete deck — REGARDLESS of any record's schedule state.
+The schedule module's review-selection surface is NEVER consulted here (it is not
+even imported in this module — the structural boundary).
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, List, Mapping, Optional, Sequence
+
+from .._schema import public_payload
+from ._budget import BudgetMeter
+from ._contract import AGENT_LEARNING_PRACTICE_UPDATE_KIND
+from ._store import ConsolidationStore
+
+# NOTE: by construction this module references no scheduling/review-selection
+# machinery (the 13D-D7 structural boundary — promotion never consults schedule
+# state). Verified by inspection in the Unit-12 test.
+
+
+def _harness_prefixes():
+    import importlib
+    return importlib.import_module("fi.opt.components").HARNESS_LAYER_PATH_PREFIXES
+
+
+def _path_in_layer(path: str, layer: str) -> bool:
+    prefixes = _harness_prefixes().get(layer, ())
+    return any(path == p or path.startswith(f"{p}.") for p in prefixes)
+
+
+def promotion_sweep(
+    store: ConsolidationStore,
+    *,
+    frozen_rows: Sequence[str],
+    replay_row: Callable[[str], bool],
+    meter: Optional[BudgetMeter] = None,
+) -> dict:
+    """Replay the FULL deck union at a candidate promotion (13D-D7 INVARIANT).
+    ``replay_row(row_id) -> bool`` returns whether the row re-closes against the
+    CURRENT config. ALL rows replay; schedule state is NEVER consulted."""
+    rows = store.full_deck(frozen_rows=list(frozen_rows))
+    vetoed: List[str] = []
+    for row_id in rows:
+        if meter is not None:
+            meter.charge("promotion_sweep", 1)
+        if not replay_row(row_id):
+            vetoed.append(row_id)
+    all_closed = not vetoed
+    return {
+        "rows_replayed": rows,
+        "row_count": len(rows),
+        "all_closed": all_closed,
+        # the existing veto shape (replay_frozen_profile rules).
+        "veto": (not all_closed),
+        "vetoed_rows": vetoed,
+        "hetvabhasa_class": "badhita" if vetoed else None,
+    }
+
+
+def update(
+    deficit: Mapping[str, Any],
+    *,
+    allowed_layer: str,
+    allowed_paths: Sequence[str],
+    proposals: Sequence[Mapping[str, Any]],
+    store: ConsolidationStore,
+    frozen_rows: Sequence[str],
+    replay_row: Callable[[str], bool],
+    meter: BudgetMeter,
+    operator_backend: str = "society",
+    budget_fraction: float = 0.0,
+) -> dict:
+    """Scoped update: enforce layer locality, invoke the inner operator (sliced
+    budget), then run the promotion sweep (the D7 point). Proposals carry the
+    panca-avayava justification; locality breaches are recorded as asiddha."""
+    allowed = list(allowed_paths)
+    locality_breaches: List[dict] = []
+    accepted_proposals: List[dict] = []
+    for proposal in proposals:
+        patch = dict(proposal.get("patch") or {})
+        breach = False
+        for path in patch:
+            if path not in allowed and not _path_in_layer(path, allowed_layer):
+                locality_breaches.append({
+                    "path": path,
+                    "expected_layer": allowed_layer,
+                    "recorded_as": "asiddha",
+                })
+                breach = True
+        accepted_proposals.append({
+            "patch": patch,
+            "justification": dict(proposal.get("justification") or {}),
+            "rejection": "asiddha" if breach else proposal.get("rejection"),
+        })
+
+    # inner operator slice charged to the meter (its declared eval_budget IS the slice).
+    budget_slice = meter.slice("update", budget_fraction) if budget_fraction else 0
+    if budget_slice:
+        meter.charge("update", min(budget_slice, meter.remaining()))
+
+    selected = next(
+        (p for p in accepted_proposals if p.get("rejection") is None), None
+    )
+
+    sweep = promotion_sweep(store, frozen_rows=frozen_rows, replay_row=replay_row, meter=meter)
+
+    record = {
+        "kind": AGENT_LEARNING_PRACTICE_UPDATE_KIND,
+        "deficit_ref": deficit.get("cell"),
+        "allowed_layer": allowed_layer,
+        "allowed_paths": allowed,
+        "operator": {"backend": operator_backend, "kwargs": {}, "budget_slice": budget_slice},
+        "proposals": accepted_proposals,
+        "locality_breaches": locality_breaches,
+        "selected_candidate": selected,
+        "promotion_sweep": sweep,
+    }
+    return public_payload(record, kind=AGENT_LEARNING_PRACTICE_UPDATE_KIND)