clm-kernel 0.0.0__py3-none-any.whl

clm/cross_cutting/vcard.py

@@ -0,0 +1,560 @@
+"""Cross-Cutting — VCard (Id-type / Application Plane / Arena + Action)
+
+Implements the VCard (Verification Card / Id-type) machinery that gates
+every state transition in the CLM system. In the MVP Cards triad:
+
+    MCard (Σ-type)  — the data state (Noun Phrase / Moore Machine)
+    PCard (Π-type)  — the transformation (Verb Phrase / Mealy Machine)
+    VCard (Id-type) — the verification witness (Sentence / Triangle Identity)
+
+The VCard Sandwich pattern (Gatekeeper Pattern) enforces the PTR lifecycle:
+
+    V_pre (precondition) → PCard (execution) → V_post (postcondition)
+
+This maps directly to Hoare Logic {P} C {Q}:
+    - prep  phase: V_pre asserts preconditions (Sum-typed / flexible ingress)
+    - exec  phase: PCard fires the transition (β-reduction)
+    - post  phase: V_post verifies postconditions (Product-typed / strict egress)
+
+Every VCard is itself stored as an MCard (Empty Schema Principle), making
+the verification trace content-addressable and permanently auditable.
+
+Design references:
+    - PTR: Polynomial Type Runtime (§Core Lifecycle)
+    - PTR Design Patterns (Gatekeeper Pattern)
+    - MVP Cards Design Rationale (The Flux Pattern)
+"""
+
+import os
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+from pydantic import BaseModel
+
+from clm.cross_cutting.cel_engine import _smart_evaluate  # Sprint 132.4: hoisted from 7 inline imports
+
+# Sprint 133.3: VCard deprecation alias removed; Card imported lazily where needed.
+from clm.cross_cutting.telemetry import jsonl_emit_typed
+from clm.cross_cutting.timeutil import now_g_time
+from clm.layer0.context import CLMContext
+
+# ---------------------------------------------------------------------------
+# Sprint 384 (DEL-384-02): Re-export canonical VCard from Layer 0 card_triad
+from clm.layer0.model.card_triad import VCard  # noqa: F401
+from clm.layer0.utils import clm_hash_string as hash_string
+
+# ---------------------------------------------------------------------------
+
+
+class Marking(BaseModel):
+    """Petri Net marking — a boundary state snapshot used by VCard gates."""
+    run_id: str
+    markings: dict[str, int]
+    colors: dict[str, str]
+
+
+# ---------------------------------------------------------------------------
+# VCard Gate
+# ---------------------------------------------------------------------------
+
+def vcard_pre_gate(
+    ctx: CLMContext,
+    pcard_hash: str,
+    triggering_dispatch_hash: str,
+    input_place_hashes: list[str],
+    timestamp: str,
+    agent_did: str,
+    sponsor_did: str,
+    delegation_proof: str,
+    execution_locale_hash: str,
+    transport_ref: str,
+) -> str:
+    """V_pre — callback gate (prep phase).
+
+    Sprint 132.4: extracted from ``vcard_gate(mode="callback")``.
+    """
+    from clm.cross_cutting.mcard import Card
+
+    card = Card(
+        token_type="vcard", gate_type="callback", result="pass",
+        pcard_hash=pcard_hash,
+        triggering_dispatch_hash=triggering_dispatch_hash,
+        timestamp=timestamp, agent_did=agent_did, sponsor_did=sponsor_did,
+        delegation_proof=delegation_proof,
+        execution_locale_hash=execution_locale_hash,
+        transport_ref=transport_ref,
+        input_place_hashes=input_place_hashes,
+    )
+    vcard_yaml = card.to_yaml()
+    vcard_hash = hash_string(vcard_yaml)
+    handle_name = f"vcard:callback:{vcard_hash}"
+    ctx.repo.save_card_and_handle(
+        handle_name, vcard_hash, vcard_yaml, "execution_log",
+        timestamp=timestamp, replace=False,
+    )
+    jsonl_emit_typed("vcard_callback", {
+        "vcard_hash": vcard_hash,
+        "gate_type": "callback",
+        "result": "pass",
+        "pcard_hash": pcard_hash,
+    }, ctx.root)
+    return vcard_hash
+
+
+def vcard_post_gate(
+    ctx: CLMContext,
+    pcard_hash: str,
+    exec_exit_code: str,
+    downstream_targets: list[str],
+    timestamp: str,
+    agent_did: str,
+    sponsor_did: str,
+    delegation_proof: str,
+    execution_locale_hash: str,
+    transport_ref: str,
+) -> str:
+    """V_post — dispatch gate (post phase).
+
+    Sprint 132.4: extracted from ``vcard_gate(mode="dispatch")``.
+    """
+    from clm.cross_cutting.mcard import Card
+
+    gate_result = "pass"
+    failure_reason = None
+    if exec_exit_code != "0":
+        gate_result = "fail"
+        failure_reason = f"PCard execution failed with exit code {exec_exit_code}"
+
+    card = Card(
+        token_type="vcard", gate_type="dispatch", result=gate_result,
+        pcard_hash=pcard_hash,
+        timestamp=timestamp, agent_did=agent_did, sponsor_did=sponsor_did,
+        delegation_proof=delegation_proof,
+        execution_locale_hash=execution_locale_hash,
+        transport_ref=transport_ref,
+        failure_reason=failure_reason,
+        downstream_callback_targets=downstream_targets,
+    )
+    vcard_yaml = card.to_yaml()
+    vcard_hash = hash_string(vcard_yaml)
+    handle_name = f"vcard:dispatch:{vcard_hash}"
+    ctx.repo.save_card_and_handle(
+        handle_name, vcard_hash, vcard_yaml, "execution_log",
+        timestamp=timestamp, replace=False,
+    )
+    jsonl_emit_typed("vcard_dispatch", {
+        "vcard_hash": vcard_hash,
+        "gate_type": "dispatch",
+        "result": gate_result,
+        "pcard_hash": pcard_hash,
+    }, ctx.root)
+    return vcard_hash
+
+
+def vcard_gate(
+    ctx: CLMContext,
+    mode: str,
+    pcard_hash: str,
+    triggering_dispatch_hash_or_exit_code: str,
+    input_place_hashes_or_downstream_targets: list[str],
+    timestamp: str,
+    agent_did: str,
+    sponsor_did: str,
+    delegation_proof: str,
+    execution_locale_hash: str,
+    transport_ref: str,
+) -> str:
+    """Generate a VCard gate (pre or post) and persist it to the execution log.
+
+    In 'callback' mode: generates V_pre (precondition gate / prep phase).
+    In 'dispatch' mode: generates V_post (postcondition gate / post phase).
+
+    .. deprecated:: Sprint 132.4
+        Prefer :func:`vcard_pre_gate` / :func:`vcard_post_gate` directly.
+    """
+    if mode == "callback":
+        return vcard_pre_gate(
+            ctx, pcard_hash,
+            triggering_dispatch_hash_or_exit_code,
+            input_place_hashes_or_downstream_targets,
+            timestamp, agent_did, sponsor_did, delegation_proof,
+            execution_locale_hash, transport_ref,
+        )
+    return vcard_post_gate(
+        ctx, pcard_hash,
+        triggering_dispatch_hash_or_exit_code,
+        input_place_hashes_or_downstream_targets,
+        timestamp, agent_did, sponsor_did, delegation_proof,
+        execution_locale_hash, transport_ref,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Gate Evaluator
+# ---------------------------------------------------------------------------
+
+class GateEvaluator:
+    """Dispatches VCard gate assertions via an extensible gate registry.
+
+    Built-in gates:
+
+    * ``gate:file_exists``      — asserts a filesystem path exists.
+    * ``gate:hash_matches``     — asserts expected == actual.
+    * ``gate:payload_nonempty`` — asserts a value is non-empty.
+    * ``gate:db_accessible``    — asserts a SQLite pillar DB has required tables.
+
+    Custom gates can be registered at runtime via :meth:`register`.
+    """
+
+    def __init__(self) -> None:
+        self._gates: dict[str, Callable] = {
+            "gate:file_exists":      self._gate_file_exists,
+            "gate:hash_matches":     self._gate_hash_matches,
+            "gate:payload_nonempty": self._gate_payload_nonempty,
+            "gate:db_accessible":    self._gate_db_accessible,
+            "gate:contains":         self._gate_contains,
+            "gate:true":             self._gate_true,
+        }
+
+    def register(self, gate_name: str, handler: Callable) -> None:
+        """Register a custom gate handler."""
+        self._gates[gate_name] = handler
+
+    # -- Pre-gate evaluation (Sprint 128.3: unified dict registry) --------
+
+    def evaluate_pre(self, item: dict, context: dict, suite: Any) -> bool:
+        """Evaluate a single ``vcard_pre`` gate item.
+
+        Returns ``True`` if the gate passed, ``False`` otherwise.
+
+        Sprint 133 §8.4: unified with ``evaluate_post`` — both call
+        ``_evaluate_gate(item, context, suite, phase="pre")``. The gate
+        handler decides what to do based on ``phase``.
+        """
+        return self._evaluate_gate(item, context, suite, phase="pre")
+
+    # -- Post-gate evaluation ----------------------------------------------
+
+    def evaluate_post(self, item: dict, context: dict, suite: Any) -> bool:
+        """Evaluate a single ``vcard_post`` gate item.
+
+        Returns ``True`` if the gate passed, ``False`` otherwise.
+
+        Sprint 133 §8.4: unified with ``evaluate_pre`` — both call
+        ``_evaluate_gate(item, context, suite, phase="post")``.
+        """
+        return self._evaluate_gate(item, context, suite, phase="post")
+
+    # -- Unified gate dispatcher (Sprint 133 §8.4) -------------------------
+
+    def _evaluate_gate(self, item: dict, context: dict, suite: Any, *, phase: str) -> bool:
+        """Unified gate dispatcher for both pre and post phases.
+
+        ``phase`` is either ``"pre"`` or ``"post"``. The handler receives
+        it as a keyword-only argument and can branch on it.
+        """
+        test_case = item.get("test_case", "")
+        gate = item.get("gate", "")
+        value_expr = item.get("value", "")
+
+        try:
+            _val = _smart_evaluate(value_expr, context)  # noqa: F841 — pre-eval to catch errors
+        except Exception as e:
+            label = "Precondition" if phase == "pre" else "Postcondition"
+            suite.tu_fail(f"VCard {label} Failed: {test_case} (Evaluation error: {e})")
+            return False
+
+        handler = self._gates.get(gate)
+        if handler is None:
+            label = "Precondition" if phase == "pre" else "Postcondition"
+            suite.tu_fail(f"Unknown VCard {label} gate: {gate}")
+            return False
+
+        try:
+            return handler(item, context, suite, test_case, phase=phase)
+        except Exception as e:
+            suite.tu_fail(f"VCard Postcondition '{test_case}' failed to evaluate: {e}")
+            return False
+
+    # -- Built-in gate handlers (unified pre/post, Sprint 133 §8.4) --------
+
+    @staticmethod
+    def _gate_file_exists(item: dict, ctx: dict, suite: Any, desc: str, *, phase: str = "post") -> bool:
+        val = _smart_evaluate(item.get("value"), ctx)
+        if phase == "pre":
+            clm_root = ctx.get("clm_root", "")
+            resolved = os.path.join(clm_root, val) if not os.path.isabs(val) else val
+            if os.path.isfile(resolved) and os.access(resolved, os.R_OK):
+                suite.tu_pass(f"VCard Precondition Passed: {desc} ({val} exists)")
+                return True
+            suite.tu_fail(f"VCard Precondition Failed: {desc} ({val} not found or not readable)")
+            return False
+        ok = os.path.isfile(val)
+        suite.assert_eq(f"File exists: {val}", True, ok)
+        return ok
+
+    @staticmethod
+    def _gate_hash_matches(item: dict, ctx: dict, suite: Any, desc: str, *, phase: str = "post") -> bool:
+        expected = _smart_evaluate(item.get("expected"), ctx)
+        actual = _smart_evaluate(item.get("actual"), ctx)
+        suite.assert_eq(desc, expected, actual)
+        return str(expected) == str(actual)
+
+    @staticmethod
+    def _gate_payload_nonempty(item: dict, ctx: dict, suite: Any, desc: str, *, phase: str = "post") -> bool:
+        val = _smart_evaluate(item.get("value"), ctx)
+        ok = val is not None and val != "" and val != []
+        if phase == "pre":
+            if ok:
+                suite.tu_pass(f"VCard Precondition Passed: {desc}")
+            else:
+                suite.tu_fail(f"VCard Precondition Failed: {desc} (payload is empty)")
+        else:
+            if ok:
+                suite.tu_pass(f"Payload non-empty: {desc}")
+            else:
+                suite.tu_fail(f"Payload is empty: {desc}")
+        return ok
+
+    @staticmethod
+    def _gate_db_accessible(item: dict, ctx: dict, suite: Any, desc: str, *, phase: str = "post") -> bool:
+        import sqlite3
+
+        args_list = item.get("args") or ([item.get("arg")] if item.get("arg") else [])
+        pillar_expr = args_list[0] if args_list and args_list[0] else "content_memory"
+        pillar = _smart_evaluate(pillar_expr, ctx) or "content_memory"
+        tmp_dir = ctx.get("tmp_dir") or ctx.get("clm_root") or os.getcwd()
+        db_file = os.path.join(tmp_dir, "db", f"{pillar}.db")
+        if not os.path.isfile(db_file):
+            suite.tu_fail(f"gate:db_accessible Failed: DB file {db_file} not found")
+            return False
+        conn = sqlite3.connect(db_file)
+        cursor = conn.cursor()
+        cursor.execute("SELECT name FROM sqlite_master WHERE type='table';")
+        tables = [row[0] for row in cursor.fetchall()]
+        conn.close()
+        if "card" in tables and "handle_registry" in tables:
+            suite.tu_pass(f"gate:db_accessible Passed: tables exist in {pillar}")
+            return True
+        suite.tu_fail(f"gate:db_accessible Failed: card or handle_registry table missing in {pillar}")
+        return False
+
+    @staticmethod
+    def _gate_contains(item: dict, ctx: dict, suite: Any, desc: str, *, phase: str = "post") -> bool:
+        expected = _smart_evaluate(item.get("expected"), ctx)
+        actual = _smart_evaluate(item.get("actual"), ctx)
+        ok = str(expected) in str(actual)
+        suite.assert_contains(desc, str(expected), str(actual))
+        return ok
+
+    @staticmethod
+    def _gate_true(item: dict, ctx: dict, suite: Any, desc: str, *, phase: str = "post") -> bool:
+        actual = _smart_evaluate(item.get("actual"), ctx)
+        ok = bool(actual)
+        suite.assert_eq(desc, True, ok)
+        return ok
+
+
+# ---------------------------------------------------------------------------
+# VCard Sandwich (Gatekeeper Pattern)
+# ---------------------------------------------------------------------------
+
+class VCardSandwich:
+    """Context manager implementing the VCard Sandwich (Gatekeeper Pattern).
+
+    Wraps every PCard execution in a pre/post verification gate, enforcing
+    the PTR prep → exec → post lifecycle as a Hoare triple {P} C {Q}:
+
+        __enter__  (prep)  — Serializes the PCard, fires V_pre callback gate.
+                             The precondition is Sum-typed: accepts any ONE
+                             valid credential from alternatives.
+        (body)     (exec)  — User code executes the PCard transition.
+        seal()     (post)  — Fires V_post dispatch gate, emits state token.
+                             The postcondition is Product-typed: ALL required
+                             outputs must be present atomically.
+
+    The sealed VCard is the constructive proof object — a term of the
+    Identity type Id(spec, actual) — certifying that the state transition
+    satisfies the specification. It is stored as an MCard in the
+    execution_log pillar of the Sovereign Triad.
+    """
+
+    def __init__(
+        self,
+        ctx: CLMContext,
+        operation: str,
+        runtime: str,
+        script_hash: str,
+        input_place_hashes: list[str],
+        agent_did: str,
+        sponsor_did: str,
+    ):
+        self.ctx = ctx
+        self.operation = operation
+        self.runtime = runtime
+        self.script_hash = script_hash
+        self.input_place_hashes = input_place_hashes
+        self.agent_did = agent_did
+        self.sponsor_did = sponsor_did
+        self.pcard_hash = ""
+
+    def __enter__(self):
+        from clm.cross_cutting.pcard import serialize_pcard
+        timestamp = now_g_time()
+        self.pcard_hash = serialize_pcard(
+            self.ctx, self.operation, self.runtime,
+            self.script_hash, self.input_place_hashes, timestamp,
+        )
+        vcard_pre_gate(
+            self.ctx, self.pcard_hash, "null", [],
+            timestamp, self.agent_did, self.sponsor_did, "self",
+            os.environ.get("CLM_EXECUTION_LOCALE_HASH", ""),
+            os.environ.get("CLM_TRANSPORT_REF", "local"),
+        )
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        # The exit hook just cleans up; seal() must be called explicitly
+        # with the execution result before exiting.
+        pass
+
+    def seal(self, exec_exit_code: int, final_content: str, store: Any = None):
+        """Seal the sandwich with the execution result.
+
+        Args:
+            exec_exit_code: 0 for success, non-zero for failure.
+            final_content: The output content to seal.
+            store: Optional CelStore — if provided, flushes the action_log
+                   to execution_log.db (Sprint 129.2).
+        """
+        from clm.cross_cutting.mcard import emit_state_failed, emit_state_token
+        timestamp = now_g_time()
+        dp_hash = vcard_post_gate(
+            self.ctx, self.pcard_hash, str(exec_exit_code), [],
+            timestamp, self.agent_did, self.sponsor_did, "self",
+            os.environ.get("CLM_EXECUTION_LOCALE_HASH", ""),
+            os.environ.get("CLM_TRANSPORT_REF", "local"),
+        )
+        if exec_exit_code == 0:
+            emit_state_token(self.ctx, self.pcard_hash, dp_hash, final_content)
+        else:
+            emit_state_failed(self.ctx, self.pcard_hash, str(exec_exit_code), final_content)
+
+        # Sprint 129.2: Flush CelStore action_log to execution_log.db
+        if store is not None and hasattr(store, "flush_action_log"):
+            store.flush_action_log(self.ctx)
+
+
+# ---------------------------------------------------------------------------
+# VCard Sandwich Decorator
+# ---------------------------------------------------------------------------
+
+def vcard_sandwich(
+    extract_ctx_func: Callable[..., CLMContext],
+    extract_meta_func: Callable[..., dict[str, Any]],
+):
+    """Decorator for wrapping an execution function in a VCard sandwich."""
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            ctx = extract_ctx_func(*args, **kwargs)
+            meta = extract_meta_func(*args, **kwargs)
+
+            with VCardSandwich(
+                ctx,
+                meta.get("operation", "unknown"),
+                meta.get("runtime", "shell"),
+                meta.get("script_hash", ""),
+                meta.get("input_place_hashes", []),
+                meta.get("agent_did", ""),
+                meta.get("sponsor_did", ""),
+            ) as sandwich:
+                res = func(*args, **kwargs)
+                if isinstance(res, tuple):
+                    exec_exit_code = res[0]
+                    final_content = res[1] if len(res) > 1 else ""
+                else:
+                    exec_exit_code = res
+                    final_content = ""
+                sandwich.seal(exec_exit_code, final_content)
+                return res
+        return wrapper
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# Monadic thunk wrapper (Sprint 129.2 — moved from cel_store.py in Sprint 132.1)
+# ---------------------------------------------------------------------------
+
+def thunk(
+    store: Any,
+    action: dict,
+    ctx: CLMContext,
+    operation: str,
+    agent_did: str = "did:clm:bootstrap",
+    dispatch_fn: Any = None,
+    post_dispatch: Any = None,
+) -> Any:
+    """Monadic thunk — wrap a dispatch in the VCardSandwich lifecycle.
+
+    Guarantees that at least one event token is registered to execution_log.db:
+        1. __enter__: serialize_pcard -> MCard in execution_log
+        2. dispatch: CelStore.dispatch(action) -> result + action_log
+        3. seal:     vcard_gate -> VCard + state_token -> execution_log
+                     flush action_log -> execution_log
+
+    This is the explicit monadic wrapper. Every function evaluation that
+    needs auditability goes through this thunk.
+
+    Sprint 133.4: extended with ``dispatch_fn`` and ``post_dispatch`` parameters
+    so ``BalancedRunner._run_case`` can use ``thunk()`` as its canonical
+    VCardSandwich lifecycle wrapper. When ``dispatch_fn`` is provided it
+    replaces the default ``store.dispatch(action)`` call. When
+    ``post_dispatch`` is provided it is called after dispatch but before
+    ``seal()``, receiving ``(sandwich, store, result)`` — enabling post-gate
+    evaluation. Returns ``(exit_code, result)`` tuple when ``dispatch_fn``
+    is used; otherwise returns the dispatch result directly.
+
+    Moved to vcard.py in Sprint 132.1 — it constructs a VCardSandwich (Id-type
+    witness machinery) and belongs next to VCardSandwich, not in cel_store.
+    """
+    from clm.cross_cutting.clm_logger import get_logger
+    from clm.layer0.utils import clm_hash_string
+
+    _logger = get_logger("clm.thunk")
+
+    pcard_hash = clm_hash_string(f"pcard:{operation}")
+    sandwich = VCardSandwich(
+        ctx=ctx, operation=operation, runtime="python",
+        script_hash=pcard_hash, input_place_hashes=[],
+        agent_did=agent_did, sponsor_did="",
+    )
+    sandwich.__enter__()
+
+    # Use dispatch_fn if provided (Sprint 133.4 — BalancedRunner path),
+    # otherwise fall back to default store.dispatch(action).
+    if dispatch_fn is not None:
+        try:
+            exit_code, result = dispatch_fn(sandwich, store)
+        except Exception as e:
+            _logger.error(f"Thunk dispatch_fn failed for operation '{operation}': {e}")
+            sandwich.seal(1, f"Exception: {e}", store=store)
+            raise
+
+        if post_dispatch is not None:
+            post_dispatch(sandwich, store, result)
+
+        sandwich.seal(exit_code, str(result) if result else "success", store=store)
+        return exit_code, result
+
+    # Default path: store.dispatch(action)
+    try:
+        result = store.dispatch(action)
+    except Exception as e:
+        _logger.error(f"Thunk dispatch failed for operation '{operation}': {e}")
+        sandwich.seal(1, f"Exception: {e}", store=store)
+        raise
+
+    sandwich.seal(0, str(result) if result else "success", store=store)
+    return result

clm/cross_cutting/writer.py

@@ -0,0 +1,118 @@
+"""StoreWriter — the Writer monad for CLM state persistence (Sprint 132.1).
+
+Extracted from ``CelStore`` in Sprint 132.1. Per the MVP Cards Design
+Rationale (quoted in Sprint 131 §1.3), ``handle_history`` is the Writer
+monad — the version trajectory. The three methods here are the Writer's
+``tell`` / ``listen`` / ``flush`` operations:
+
+    - ``set_persisted``  → ``tell``:  commits a new Card version under a handle.
+    - ``select_card``     → ``listen``: reads the current (or historical) Card.
+    - ``flush_action_log`` → ``flush``: persists the action trajectory.
+
+``CelStore`` holds a ``self.writer`` reference and delegates to it,
+preserving the existing ``store.set_persisted()`` call surface.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+
+from clm.cross_cutting.timeutil import default_agent_did
+
+if TYPE_CHECKING:
+    from clm.cross_cutting.cel_store import CelStore
+
+
+class StoreWriter:
+    """Writer monad for handle-backed state persistence."""
+
+    def __init__(self, store: "CelStore") -> None:
+        self._store = store
+
+    @property
+    def _state(self) -> Any:
+        return self._store.state
+
+    @property
+    def _services(self) -> Any:
+        return self._store.services
+
+    def set_persisted(self, key: str, value: Any, pillar: str = "execution_log") -> Any:
+        """Persist ``value`` as a Card under handle ``cel:var:<key>`` (version-tracked).
+
+        Also keeps the raw value in ``state.vars`` so the existing in-memory
+        ``retrieve()``/``select()`` contract is unchanged.
+        """
+        from clm.cross_cutting.mcard import Card
+
+        repo = self._services.repo
+        if repo is None:
+            raise RuntimeError("set_persisted requires a repo in services")
+
+        card = value if isinstance(value, Card) else Card(
+            token_type="mcard", content=str(value),
+            agent_did=default_agent_did(),
+        )
+        handle_name = f"cel:var:{key}"
+        repo.save_card_and_handle(
+            handle_name, card.compute_hash(), card.to_yaml(), pillar,
+            timestamp=card.g_time, replace=True,
+        )
+        # Sprint 132.6: bind via set_card so card_vars tracks the handle
+        self._state.set_card(key, handle_name, value)
+        return value
+
+    def select_card(self, ref: str) -> Any:
+        """Like ``CelStore.select``, but resolves handle-backed state to a ``Card``."""
+        from clm.cross_cutting.mcard import Card
+
+        parts = ref.split(".", 2)
+        ns = parts[0]
+        key = parts[1] if len(parts) > 1 else ""
+
+        if ns == "state":
+            repo = self._services.repo
+            if repo is None:
+                return None
+            # Sprint 132.6: check card_vars first (opt-in Card-backed path)
+            handle_name = self._state.card_vars.get(key, f"cel:var:{key}")
+            h = repo.resolve_handle_hash(handle_name, "execution_log")
+            if h:
+                content = repo.get_card_content(h, "execution_log")
+                if content:
+                    try:
+                        return Card.from_yaml(content)
+                    except Exception:
+                        return None
+            return None
+
+        val = self._store.select(ref)
+        if val is None:
+            return None
+        return Card(token_type="mcard", content=str(val))
+
+    def flush_action_log(self, ctx: Any) -> str | None:
+        """Flush the in-memory action_log to execution_log.db."""
+        if not self._store.action_log:
+            return None
+
+        run_id = os.environ.get("CLM_RUN_ID", "")
+        if not run_id:
+            return None
+
+        from clm.cross_cutting.clm_logger import get_logger
+        from clm.cross_cutting.telemetry import jsonl_emit_typed
+
+        _logger = get_logger("clm.store")
+
+        for entry in self._store.action_log:
+            jsonl_emit_typed("cel_action", {
+                "op": entry.get("op", "unknown"),
+                "action": entry.get("action", {}),
+                "result": entry.get("result", ""),
+                "rejected": entry.get("rejected", False),
+            }, ctx.root)
+
+        _logger.debug(f"flush_action_log: {len(self._store.action_log)} entries persisted to run:{run_id}:events")
+        return run_id