clm-kernel 0.0.0__py3-none-any.whl

clm/layer1/engine_async.py

@@ -0,0 +1,89 @@
+"""AsyncPTREngine - Asynchronous interface for the Polynomial Type Runtime (PTR)
+
+Provides native async/await methods by delegating to the existing synchronous
+PTREngine using asyncio.to_thread dynamically.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from clm.layer1.engine import ExecutionResult, PTREngine
+from clm.layer1.store import PTRSharedStore
+
+
+class AsyncPTREngine:
+    """Asynchronous wrapper for PTREngine.
+
+    Dynamically proxies all synchronous PTREngine methods into asyncio thread pool.
+    """
+
+    def __init__(
+        self,
+        storage_collection: Any | None = None,
+        execution_log_collection: Any | None = None,
+        identity_space_collection: Any | None = None,
+        **engine_kwargs: Any,
+    ) -> None:
+        self._engine = PTREngine(
+            storage_collection=storage_collection,
+            execution_log_collection=execution_log_collection,
+            identity_space_collection=identity_space_collection,
+            **engine_kwargs,
+        )
+        # Preserve public properties
+        self.logger = self._engine.logger
+        self.correctness_tracker = self._engine.correctness_tracker
+        self.collection = self._engine.collection
+
+    async def execute_pcard(
+        self,
+        pcard_hash: str,
+        target_hash: str,
+        context: dict[str, Any] | PTRSharedStore | None = None,
+        specification_embedding: list[float] | None = None,
+    ) -> ExecutionResult:
+        """Fast-path execute_pcard with optional artifact preloading."""
+        # Async prefetch artifacts using CardCollection.aget when available
+        store = getattr(self._engine, "collection", None)
+
+        if isinstance(context, PTRSharedStore):
+            pre_context = context
+            if store and hasattr(store, "aget"):
+                pcard = await store.aget(pcard_hash)
+                target = await store.aget(target_hash)
+                pre_context.inputs["_preloaded_pcard"] = pcard
+                pre_context.inputs["_preloaded_target"] = target
+        else:
+            pre_context = dict(context or {})
+            if store and hasattr(store, "aget"):
+                pcard = await store.aget(pcard_hash)
+                target = await store.aget(target_hash)
+                pre_context["_preloaded_pcard"] = pcard
+                pre_context["_preloaded_target"] = target
+
+        return await asyncio.to_thread(
+            self._engine.execute_pcard,
+            pcard_hash,
+            target_hash,
+            pre_context,
+            specification_embedding,
+        )
+
+    def __getattr__(self, name: str) -> Any:
+        """Dynamically propagate all other methods from PTREngine.
+
+        Automatically wraps callable methods in asyncio.to_thread to make them asynchronous.
+        """
+        attr = getattr(self._engine, name)
+
+        # If it's not a method or it's a private attribute, return as-is
+        if not callable(attr) or name.startswith("_"):
+            return attr
+
+        # Create an async wrapper for the synchronous method
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return await asyncio.to_thread(attr, *args, **kwargs)
+
+        return async_wrapper

clm/layer1/eval_callback.py

@@ -0,0 +1,49 @@
+"""Evaluation Callback Registry — Dependency inversion for Layer 1.
+
+Sprint 143 V-2/V-3 fix: Layer 1 (petri.py, runtime_adapter.py) was importing
+evaluate_cmd from higher layers, creating upward dependencies that violate
+the Type Lattice SSOT principle (type_lattice.md §4.5).
+
+This module provides a registry where higher layers can register their evaluate_cmd
+function at startup. Layer 1 calls get_evaluate_callback() to retrieve it,
+avoiding any direct upward import.
+
+Usage in higher layers:
+    from clm.layer1.eval_callback import register_evaluate_callback
+    register_evaluate_callback(evaluate_cmd)
+
+Usage in Layer 1:
+    from clm.layer1.eval_callback import get_evaluate_callback
+    cb = get_evaluate_callback()
+    if cb:
+        rc = cb(clm_root, clm_file, extra_args)
+"""
+
+from typing import Callable, Optional
+
+# Type alias: evaluate_cmd(clm_root: str, clm_file: str, extra_args: list[str]) -> int
+EvaluateFn = Callable[[str, str, list[str]], int]
+
+_callback: Optional[EvaluateFn] = None
+
+
+def register_evaluate_callback(fn: EvaluateFn) -> None:
+    """Register the evaluate_cmd function from Layer 3."""
+    global _callback
+    _callback = fn
+
+
+def get_evaluate_callback() -> Optional[EvaluateFn]:
+    """Retrieve the registered evaluate_cmd, or None if not yet registered."""
+    return _callback
+
+
+def evaluate_or_fail(clm_root: str, clm_file: str, extra_args: list[str]) -> int:
+    """Call the registered evaluate_cmd, or raise if no callback is registered."""
+    cb = get_evaluate_callback()
+    if cb is None:
+        raise RuntimeError(
+            "No evaluate callback registered. "
+            "Layer 3 must call register_evaluate_callback() at import time."
+        )
+    return cb(clm_root, clm_file, extra_args)

clm/layer1/gate_composer.py

@@ -0,0 +1,229 @@
+"""CLM Gate Composer — Gate PCard composition and nested evaluation.
+
+Handles the sequencing and execution of pre/post gate PCards
+in the CLM evaluation lifecycle:
+- compose_conditions_cmd: resolve and run pre/post gate PCards in sequence
+- run_nested_evaluate: execute a gate PCard in an isolated subprocess sandbox
+"""
+
+import os
+import subprocess
+import sys
+import threading
+from collections.abc import Callable
+
+from clm.cross_cutting.clm_logger import get_logger
+from clm.layer0.utils import resolve_clm_path
+
+from .verifier import get_load_manifest, validate_postcondition, verify_precondition
+
+_logger = get_logger("clm.layer1.gate_composer")
+HASH_PREFIX = "sha256:"
+
+
+def run_nested_evaluate(clm_root: str, gate_file: str, target_clm: str, exit_code: int | None = None) -> int:
+    """
+    Runs a nested evaluation of a gate PCard in an isolated sandbox.
+
+    Args:
+        clm_root (str): The root directory of the CLM workspace.
+        gate_file (str): The gate PCard to evaluate.
+        target_clm (str): The target PCard being gated.
+        exit_code (Optional[int]): Optional exit code context for post-gates.
+
+    Returns:
+        int: The return code of the nested sandbox.
+    """
+    gate_file = resolve_clm_path(clm_root, gate_file)
+    target_clm = resolve_clm_path(clm_root, target_clm)
+    engine_py = os.path.join(clm_root, "kernel/scripts/clm_runner.py")
+    cmd = [sys.executable, engine_py, "evaluate", gate_file, target_clm]
+    if exit_code is not None:
+        cmd.append(str(exit_code))
+    env = os.environ.copy()
+    env["CLM_NESTED_EXEC"] = "1"
+    env["CLM_NESTED_FILE"] = os.path.abspath(gate_file)
+    env["CLM_SKIP_CONDITIONS"] = "1"
+    proc = subprocess.Popen(cmd, env=env)
+    proc.wait()
+    return proc.returncode
+
+def compose_conditions_cmd(clm_root: str, clm_file: str, phase: str, exit_code: int = 0) -> int:
+    """
+    Composes and runs the sequence of gate PCards for a given execution phase (pre or post).
+
+    Args:
+        clm_root (str): The root directory of the CLM workspace.
+        clm_file (str): The target PCard being executed.
+        phase (str): The phase of execution ('pre' or 'post').
+        exit_code (int): The exit code from the execution (for 'post' phase).
+
+    Returns:
+        int: The exit code of the gate evaluations. 0 if successful, non-zero otherwise.
+    """
+    load_normalized_manifest = get_load_manifest()
+    clm_file = resolve_clm_path(clm_root, clm_file)
+    custom_pcard = None
+    if os.path.exists(clm_file):
+        try:
+            data = load_normalized_manifest(clm_root, clm_file)
+            inner = data.get("clm", data)
+            concrete = inner.get("concrete_impl", {})
+            if phase == "pre":
+                pre = concrete.get("precondition", {})
+                if pre:
+                    custom_pcard = pre.get("vcard_pre")
+            elif phase == "post":
+                post = concrete.get("postcondition", {})
+                if post:
+                    custom_pcard = post.get("vcard_post")
+        except Exception:
+            pass
+
+    if custom_pcard:
+        orig_custom_pcard = custom_pcard
+        if custom_pcard.startswith("gate:"):
+            gate_name = custom_pcard.split("gate:")[1]
+            custom_pcard = f"computable_knowledge/Abstract/layer5_system/bootstrap/governance/gates/{gate_name}.yaml"
+        elif custom_pcard.startswith(HASH_PREFIX):
+            target = "clm.layer2.storage"
+            mod = sys.modules.get(target)
+            if mod is None:
+                __import__(target)
+                mod = sys.modules.get(target)
+            if mod is not None:
+                db = mod.CLMDB(clm_root)
+                repo = mod.CLMRepository(db, clm_root)
+                handle = repo.get_handle_by_hash(custom_pcard, "content_memory")
+                if handle and handle.startswith("gate:"):
+                    gate_name = handle.split("gate:")[1]
+                    custom_pcard = f"computable_knowledge/Abstract/layer5_system/bootstrap/governance/gates/{gate_name}.yaml"
+
+        resolved_custom_pcard = resolve_clm_path(clm_root, custom_pcard)
+        custom_gate = None
+        if resolved_custom_pcard and os.path.exists(resolved_custom_pcard):
+            try:
+                gate_data = load_normalized_manifest(clm_root, resolved_custom_pcard)
+                inner_gate = gate_data.get("clm", gate_data)
+                custom_gate = inner_gate.get("concrete_impl", {}).get("operation")
+            except Exception:
+                pass
+
+        if custom_gate:
+            _logger.info(f"[COMPOSE] Discovered custom {phase} gate: {custom_gate} (from {orig_custom_pcard})")
+
+    override_gate = os.environ.get("CLM_GATE_OVERRIDE", "0") == "1"
+    expr = ""
+    if phase == "pre":
+        if custom_pcard:
+            if override_gate:
+                expr = custom_pcard
+            elif custom_pcard in ["computable_knowledge/Abstract/layer5_system/bootstrap/evaluator/verify_precondition.yaml", "computable_knowledge/Abstract/layer5_system/bootstrap/governance/gates/payload_nonempty.yaml"]:
+                expr = "computable_knowledge/Abstract/layer5_system/bootstrap/evaluator/verify_precondition.yaml"
+            else:
+                expr = f"computable_knowledge/Abstract/layer5_system/bootstrap/evaluator/verify_precondition.yaml >>> {custom_pcard}"
+        else:
+            expr = "computable_knowledge/Abstract/layer5_system/bootstrap/evaluator/verify_precondition.yaml"
+    else:
+        if custom_pcard:
+            if override_gate:
+                expr = custom_pcard
+            elif custom_pcard in ["computable_knowledge/Abstract/layer5_system/bootstrap/evaluator/validate_postcondition.yaml", "computable_knowledge/Abstract/layer5_system/bootstrap/governance/gates/result_sealed.yaml"]:
+                expr = "computable_knowledge/Abstract/layer5_system/bootstrap/evaluator/validate_postcondition.yaml"
+            else:
+                expr = f"computable_knowledge/Abstract/layer5_system/bootstrap/evaluator/validate_postcondition.yaml >>> {custom_pcard}"
+        else:
+            expr = "computable_knowledge/Abstract/layer5_system/bootstrap/evaluator/validate_postcondition.yaml"
+
+    seq_gates = [g.strip() for g in expr.split(">>>")]
+    for gate in seq_gates:
+        if not gate:
+            continue
+        _logger.info(f"[COMPOSE] Executing Gate: {gate}")
+        if gate == "computable_knowledge/Abstract/layer5_system/bootstrap/evaluator/verify_precondition.yaml":
+            if not verify_precondition(clm_root, clm_file):
+                _logger.info("CRITICAL: Pre-Gate Failed.")
+                return 1
+        elif gate == "computable_knowledge/Abstract/layer5_system/bootstrap/evaluator/validate_postcondition.yaml":
+            if not validate_postcondition(clm_root, clm_file, exit_code):
+                _logger.info("CRITICAL: Post-Gate Failed.")
+                return 1
+        else:
+            rc = run_nested_evaluate(clm_root, gate, clm_file, exit_code if phase == "post" else None)
+            if rc != 0:
+                _logger.info(f"CRITICAL: Gate {gate} Failed with exit code {rc}")
+                return rc
+    return 0
+
+def execute_composed_pcard_py(
+    clm_root: str,
+    expr: str,
+    phase: str,
+    exit_code: int = 0,
+    payload: str = "",
+    lookup: dict[str, Callable] | None = None
+) -> int:
+    """
+    Python-native monadic composition executor.
+    Supports >>> (sequential), ⊗ (tensor/parallel), and id (passthrough).
+    """
+    if lookup is None:
+        lookup = {}
+
+    expr = expr.strip()
+    if not expr or expr == "id":
+        return 0
+
+    # 1. Sequential composition (>>>) has lowest precedence (splits first)
+    if ">>>" in expr:
+        # Split by >>>
+        parts = [p.strip() for p in expr.split(">>>")]
+        for part in parts:
+            if not part:
+                continue
+            rc = execute_composed_pcard_py(clm_root, part, phase, exit_code, payload, lookup)
+            if rc != 0:
+                return rc
+        return 0
+
+    # 2. Tensor Product Composition (⊗)
+    if "⊗" in expr:
+        parts = [p.strip() for p in expr.split("⊗")]
+        threads = []
+        results = []
+
+        def worker(part):
+            rc = execute_composed_pcard_py(clm_root, part, phase, exit_code, payload, lookup)
+            results.append(rc)
+
+        for part in parts:
+            if not part:
+                continue
+            t = threading.Thread(target=worker, args=(part,))
+            threads.append(t)
+            t.start()
+
+        for t in threads:
+            t.join()
+
+        for rc in results:
+            if rc != 0:
+                return rc
+        return 0
+
+    # 3. Base case: single gate
+    gate = expr
+    if gate in lookup:
+        func = lookup[gate]
+        try:
+            rc = func(payload) if phase == "pre" else func(exit_code, payload)
+            if isinstance(rc, bool):
+                return 0 if rc else 1
+            if rc is None:
+                return 0
+            return int(rc)
+        except Exception as e:
+            _logger.error(f"[COMPOSE] Error running gate function '{gate}': {e}")
+            return 1
+
+    return run_nested_evaluate(clm_root, gate, payload, exit_code if phase == "post" else None)

clm/layer1/hoare_sandwich.py

@@ -0,0 +1,298 @@
+"""Declarative VCard Hoare Sandwich Engine (Sprint 394 / DEL-394-01).
+
+Implements the formal Hoare Triple verification lifecycle:
+    {V_pre} Action {V_post}
+Enforces pre-condition invariant gating, operator execution, post-condition lattice
+witness certification, and atomic <1.0ms rollback on violation.
+
+Acceptance Criteria:
+- AC-394-01-01: Passing V_pre & V_post completes Z4 lifecycle, outputs certified MCard & VCardReceipt.
+- AC-394-01-02: Failing V_pre aborts with PreconditionBreachError without invoking operator.
+- AC-394-01-03: Failing V_post triggers <1ms atomic rollback, raising PostconditionBreachError.
+
+Layer 1 module (no static imports above L1).
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from clm.cross_cutting.domain_models import MCard
+from clm.layer0.exceptions import CLMError
+from clm.layer0.model.action import ActionManifest
+from clm.layer0.model.card_triad import compute_canonical_hash
+from clm.layer0.rule_evaluator import SafeRuleEvaluator
+from clm.layer1.action_dispatcher import ActionDispatcher
+from clm.layer1.savepoint_guard import VCardMeetViolation, z4_savepoint_guard
+
+
+class PreconditionBreachError(CLMError):
+    """Raised when an Action precondition (V_pre) evaluates to false."""
+
+
+class PostconditionBreachError(CLMError):
+    """Raised when an Action postcondition (V_post) evaluates to false, triggering rollback."""
+
+
+@dataclass(frozen=True)
+class HoareSandwichResult:
+    """Certified result of an Action executed inside the Hoare Sandwich."""
+
+    status: str
+    action_name: str
+    outputs: dict[str, MCard] = field(default_factory=dict)
+    receipt: MCard | None = None
+    precondition_verdicts: list[dict[str, Any]] = field(default_factory=list)
+    postcondition_verdicts: list[dict[str, Any]] = field(default_factory=list)
+    rollback_occurred: bool = False
+    rollback_time_ms: float = 0.0
+    metrics: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+
+    @property
+    def is_success(self) -> bool:
+        return self.status == "success"
+
+
+class HoareSandwichEngine:
+    """Executes Action manifests within the {V_pre} Action {V_post} Hoare Sandwich."""
+
+    @classmethod
+    def execute(
+        cls,
+        manifest: ActionManifest | str | Path | dict[str, Any],
+        input_bindings: dict[str, Any] | None = None,
+        fs: Any = None,
+    ) -> HoareSandwichResult:
+        """Execute Action with full pre- and post-condition verification."""
+        t_start = time.perf_counter()
+
+        # 1. Parse manifest
+        if isinstance(manifest, (str, Path)):
+            action = ActionManifest.from_yaml(manifest)
+        elif isinstance(manifest, dict):
+            action = ActionManifest.from_dict(manifest)
+        elif isinstance(manifest, ActionManifest):
+            action = manifest
+        else:
+            raise TypeError(f"Invalid manifest type: {type(manifest)}")
+
+        action_hash = compute_canonical_hash(action.to_dict())
+
+        # 2. Build Precondition Context
+        bindings = dict(input_bindings or {})
+        if fs is not None:
+            for k, v in list(bindings.items()):
+                if isinstance(v, str) and (v.startswith("mcard:") or v.startswith("mcard://")):
+                    clean_uri = v
+                    if clean_uri.startswith("mcard://"):
+                        clean_uri = "mcard:" + clean_uri[len("mcard://"):]
+                    try:
+                        resolved_card = fs.read_file(clean_uri)
+                        if resolved_card is not None:
+                            bindings[k] = resolved_card
+                    except Exception:
+                        pass
+
+        pre_ctx: dict[str, Any] = {}
+        for inp in action.inputs:
+            bound_val = bindings.get(inp.name)
+            if bound_val is not None:
+                card_or_data = bound_val.payload if isinstance(bound_val, MCard) else bound_val
+                ctx_info = cls._build_item_context(card_or_data, bound_val)
+                pre_ctx[inp.name] = ctx_info
+                # Also expose single input as 'input'
+                if len(action.inputs) == 1 or inp.name == "dataset":
+                    pre_ctx["input"] = ctx_info
+
+        # 3. Phase 1: Evaluate Preconditions (V_pre)
+        pre_verdicts: list[dict[str, Any]] = []
+        for pre in action.preconditions:
+            try:
+                passed = SafeRuleEvaluator.evaluate(pre.rule, pre_ctx)
+            except Exception as e:
+                raise PreconditionBreachError(
+                    f"Precondition '{pre.invariant}' evaluation error: {e}"
+                ) from e
+
+            verdict = {
+                "invariant": pre.invariant,
+                "rule": pre.rule,
+                "passed": passed,
+                "description": pre.description,
+            }
+            pre_verdicts.append(verdict)
+
+            # AC-394-01-02: Abort immediately prior to operator execution
+            if not passed:
+                raise PreconditionBreachError(
+                    f"Precondition '{pre.invariant}' violated: '{pre.rule}' evaluated to false"
+                )
+
+        # 4. Phase 2 & 3: Savepoint-Guarded Execution and Postcondition Verification
+        # If filesystem has a connection, wrap in z4_savepoint_guard
+        conn = getattr(fs, "conn", None)
+
+        if conn is not None:
+            # Transactional Savepoint Guard active
+            try:
+                with z4_savepoint_guard(conn, step_id=f"hoare_{action.clm.name}") as guard:
+                    exec_result = ActionDispatcher.execute(action, bindings, fs=fs)
+                    if not exec_result.is_success:
+                        guard.fail_meet(exec_result.error or "Operator execution failure")
+
+                    # Phase 3: Evaluate Postconditions (V_post)
+                    post_ctx = cls._build_post_context(pre_ctx, exec_result.outputs)
+                    post_verdicts = cls._eval_postconditions(action.postconditions, post_ctx)
+
+                    # Advance guard to commit
+                    guard.advance_phase(3)
+
+            except VCardMeetViolation as e:
+                raise PostconditionBreachError(f"Postcondition breach: {e}") from e
+
+        else:
+            # In-memory execution without direct sqlite connection
+            exec_result = ActionDispatcher.execute(action, bindings, fs=fs)
+            if not exec_result.is_success:
+                raise CLMError(f"Action execution failed: {exec_result.error}")
+
+            post_ctx = cls._build_post_context(pre_ctx, exec_result.outputs)
+            post_verdicts = cls._eval_postconditions(action.postconditions, post_ctx)
+
+        # 5. Phase 4: Generate VCardReceipt and complete Hoare Sandwich
+        receipt = cls._generate_receipt(
+            action_name=action.clm.name,
+            action_hash=action_hash,
+            input_hashes=exec_result.input_hashes,
+            output_hashes=exec_result.output_hashes,
+            pre_verdicts=pre_verdicts,
+            post_verdicts=post_verdicts,
+            metrics=exec_result.metrics,
+        )
+
+        t_elapsed = (time.perf_counter() - t_start) * 1000.0
+
+        return HoareSandwichResult(
+            status="success",
+            action_name=action.clm.name,
+            outputs=exec_result.outputs,
+            receipt=receipt,
+            precondition_verdicts=pre_verdicts,
+            postcondition_verdicts=post_verdicts,
+            metrics={
+                **exec_result.metrics,
+                "hoare_total_time_ms": round(t_elapsed, 3),
+            },
+        )
+
+    @classmethod
+    def _eval_postconditions(
+        cls,
+        postconditions: list[Any],
+        context: dict[str, Any],
+    ) -> list[dict[str, Any]]:
+        """Evaluate all postconditions, raising PostconditionBreachError on failure."""
+        post_verdicts: list[dict[str, Any]] = []
+        for post in postconditions:
+            try:
+                passed = SafeRuleEvaluator.evaluate(post.rule, context)
+            except Exception as e:
+                raise PostconditionBreachError(
+                    f"Postcondition '{post.invariant}' evaluation error: {e}"
+                ) from e
+
+            verdict = {
+                "invariant": post.invariant,
+                "rule": post.rule,
+                "passed": passed,
+                "description": post.description,
+            }
+            post_verdicts.append(verdict)
+
+            # AC-394-01-03: Failing postcondition halts execution and triggers rollback
+            if not passed:
+                raise PostconditionBreachError(
+                    f"Postcondition '{post.invariant}' violated: '{post.rule}' evaluated to false"
+                )
+        return post_verdicts
+
+    @staticmethod
+    def _build_item_context(payload: Any, card: Any = None) -> dict[str, Any]:
+        """Extract structured properties for rule evaluation context."""
+        ctx: dict[str, Any] = {}
+        if isinstance(payload, str):
+            ctx["size_bytes"] = len(payload.encode("utf-8"))
+            lines = [ln for ln in payload.splitlines() if ln.strip()]
+            ctx["line_count"] = len(lines)
+            if lines and ("," in lines[0] or "\t" in lines[0]):
+                cols = [c.strip() for c in lines[0].split(",")]
+                ctx["columns"] = cols
+                ctx["column_count"] = len(cols)
+                ctx["row_count"] = len(lines) - 1
+        elif isinstance(payload, bytes):
+            ctx["size_bytes"] = len(payload)
+        elif isinstance(payload, dict):
+            ctx["keys"] = list(payload.keys())
+            ctx["key_count"] = len(payload)
+            ctx.update(payload)
+        elif isinstance(payload, list):
+            ctx["item_count"] = len(payload)
+            ctx["row_count"] = len(payload)
+
+        if card and hasattr(card, "metadata") and isinstance(card.metadata, dict):
+            ctx.update(card.metadata)
+
+        return ctx
+
+    @classmethod
+    def _build_post_context(
+        cls,
+        pre_ctx: dict[str, Any],
+        outputs: dict[str, MCard],
+    ) -> dict[str, Any]:
+        """Assemble combined context (input + output) for postcondition evaluation."""
+        post_ctx = dict(pre_ctx)
+        out_dict: dict[str, Any] = {}
+        for name, card in outputs.items():
+            info = cls._build_item_context(card.payload, card)
+            out_dict[name] = info
+
+        post_ctx["output"] = out_dict
+        if len(outputs) == 1:
+            # Expose primary output attributes directly on 'output'
+            primary_name = next(iter(outputs.keys()))
+            post_ctx["output"].update(out_dict[primary_name])
+
+        return post_ctx
+
+    @staticmethod
+    def _generate_receipt(
+        action_name: str,
+        action_hash: str,
+        input_hashes: dict[str, str],
+        output_hashes: dict[str, str],
+        pre_verdicts: list[dict[str, Any]],
+        post_verdicts: list[dict[str, Any]],
+        metrics: dict[str, Any] | None = None,
+    ) -> MCard:
+        """Deferred dynamic invocation of Layer 2 VCardReceipt generator."""
+        target = "clm.layer2.vcard_receipt"
+        mod = sys.modules.get(target)
+        if mod is None:
+            __import__(target)
+            mod = sys.modules.get(target)
+        fn = mod.generate_vcard_receipt
+        return fn(
+            action_name=action_name,
+            action_hash=action_hash,
+            input_hashes=input_hashes,
+            output_hashes=output_hashes,
+            precondition_verdicts=pre_verdicts,
+            postcondition_verdicts=post_verdicts,
+            metrics=metrics,
+        )