velm 0.1.2__py3-none-any.whl

velm/core/kernel/transaction/chronicle_bridge.py

@@ -0,0 +1,217 @@
+# Path: scaffold/core/kernel/transaction/chronicle_bridge.py
+# ----------------------------------------------------------
+import json
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, List, Dict, Any, Set
+
+# --- THE DIVINE SUMMONS OF PERCEPTION ---
+from ....inquisitor import get_treesitter_gnosis
+from ....contracts.data_contracts import GnosticWriteResult, InscriptionAction
+from ....logger import Scribe
+
+if TYPE_CHECKING:
+    from ..transaction.facade import GnosticTransaction
+
+Logger = Scribe("ChronicleBridge")
+
+
+class ChronicleBridge:
+    """
+    =================================================================================
+    == THE SCRIBE'S EMISSARY (V-Ω-ETERNAL-APOTHEOSIS-ULTIMA++)                     ==
+    =================================================================================
+    LIF: 10,000,000,000,000,000,000 (THE KEEPER OF THE ETERNAL SCROLL)
+
+    This divine artisan is the one true, sentient conduit between an active
+    Transaction and the eternal Gnostic Chronicle (`scaffold.lock`). It is a
+    Forensic Inquisitor that enriches the raw data of a rite with deep, structural
+    Gnosis before commanding the High Scribe to seal it into history.
+
+    ### THE PANTHEON OF 12 ASCENDED FACULTIES:
+
+    1.  **The Structural Enshrinement (THE FIX):** It now surgically extracts the
+        souls of Functions and Classes from the ephemeral AST dossier and embeds
+        them into the persistent `metrics` vessel. This ensures the `GnosticDatabase`
+        can resurrect the full symbol map even from a cold, dead lockfile.
+    2.  **The Gnostic Linker:** Performs a deep, two-pass Gaze to resolve raw
+        imported symbols into fully-resolved file paths, forging the unbreakable
+        bonds of the dependency graph.
+    3.  **The Unbreakable Ward of Gnosis:** It wraps the AST extraction in a
+        shielded block, ensuring that a parsing paradox does not halt the sealing
+        of the chronicle.
+    4.  **The Lazy Staging Gaze:** It reads content directly from the Staging Area,
+        ensuring it perceives the *intended* reality before it is even committed
+        to the mortal realm.
+    5.  **The Module Path Alchemist:** It correctly calculates the Pythonic dotted
+        path for every file, handling `__init__.py` logic with divine precision.
+    6.  **The Symbol Map Forge:** It constructs a temporary, high-speed map of
+        `Symbol -> FilePath` to resolve dependencies with O(1) lookups.
+    7.  **The Dependency Weaver:** It updates the `result.dependencies` list with
+        the resolved paths, creating a causal link between scriptures.
+    8.  **The Filter of Relevance:** It only gazes upon scriptures that were
+        Created, Transfigured, or Adopted, ignoring those untouched by the rite.
+    9.  **The Metadata Injector:** It enriches the `GnosticWriteResult` with
+        cyclomatic complexity metrics and other deep insights.
+    10. **The Encoding Healer:** It reads file content with `errors='ignore'`,
+        forgiving minor encoding heresies to preserve the greater truth.
+    11. **The Luminous Voice:** It proclaims its progress to the log, revealing
+        the depth of its perception.
+    12. **The Sovereign Bridge:** It acts as the final preparation stage before
+        the `ManifestFederator` merges the new truth into the eternal timeline.
+    =================================================================================
+    """
+
+    def __init__(self, transaction: "GnosticTransaction"):
+        self.tx = transaction
+
+    def seal_chronicle(self):
+        """The Grand Rite of Sealing. Gathers all Gnosis and summons the High Scribe."""
+        if not self.tx.write_dossier and not self.tx.edicts_executed:
+            Logger.verbose("Hollow rite perceived. The Chronicle remains untouched.")
+            return
+
+        Logger.info(f"The Chronicle Bridge awakens. Sealing the history of '{self.tx.rite_name}'...")
+        start_time = time.monotonic()
+
+        old_lock_data = {}
+        main_lock_path = self.tx.project_root / "scaffold.lock"
+        if main_lock_path.exists():
+            try:
+                old_lock_data = json.loads(main_lock_path.read_text(encoding='utf-8'))
+            except (json.JSONDecodeError, IOError):
+                Logger.warn(
+                    "Could not read previous chronicle for federation; it may be profane. Forging a new history.")
+
+        # ★★★ THE DIVINE HEALING ★★★
+        # The Rite of Gnostic Enrichment is the final word before sealing.
+        # We ensure the write dossier currently held in memory is fully enriched.
+        # Note: The Transaction calls _enrich_if_needed() before commit, which calls this class's _enrich_dossier().
+        # However, to be absolutely safe, we reference the values which are updated in-place.
+        enriched_dossier = list(self.tx.write_dossier.values())
+        # ★★★ THE APOTHEOSIS IS COMPLETE ★★★
+
+        from ..chronicle import update_chronicle
+
+        update_chronicle(
+            project_root=self.tx.project_root,
+            blueprint_path=self.tx.blueprint_path,
+            rite_dossier={},
+            old_lock_data=old_lock_data,
+            write_dossier=enriched_dossier,
+            final_vars=self.tx.context,
+            rite_name=self.tx.rite_name,
+            edicts_executed=self.tx.edicts_executed,
+            heresies_perceived=self.tx.heresies_perceived
+        )
+
+        duration = (time.monotonic() - start_time) * 1000
+        Logger.success(f"Chronicle sealed in {duration:.2f}ms.")
+
+    def _enrich_dossier(self) -> List[GnosticWriteResult]:
+        """
+        [THE TRUE GNOSTIC LINKER - V-Ω-APOTHEOSIS]
+        Performs a deep, two-pass Gaze to resolve symbols to file paths and
+        embed structural souls into the persistent metrics.
+        """
+        items_to_scan = [
+            res for res in self.tx.write_dossier.values()
+            if res.success and res.action_taken in (InscriptionAction.CREATED, InscriptionAction.TRANSFIGURED,
+                                                    InscriptionAction.SYMBIOTIC_MERGE, InscriptionAction.ADOPTED)
+        ]
+
+        if not items_to_scan:
+            return list(self.tx.write_dossier.values())
+
+        Logger.verbose(f"The Soul-Reader awakens its Two-Pass Gaze upon {len(items_to_scan)} scripture(s)...")
+
+        raw_gnosis_map: Dict[Path, Dict] = {}
+        symbol_map: Dict[str, str] = {}
+
+        # --- PASS 1: GNOSTIC CENSUS & STRUCTURAL ENSHRINEMENT ---
+        for result in items_to_scan:
+            try:
+                staged_path = self.tx.get_staging_path(result.path)
+                if not staged_path.is_file(): continue
+
+                content = staged_path.read_bytes().decode('utf-8', errors='ignore')
+
+                # The Inquisitor perceives the AST
+                gnosis = get_treesitter_gnosis(staged_path, content)
+                raw_gnosis_map[result.path] = gnosis
+
+                if gnosis and "error" not in gnosis:
+                    # [THE FIX: STRUCTURAL EMBEDDING]
+                    # We surgically extract the structural soul (functions/classes) and
+                    # embed it into the 'metrics' payload. This payload is what gets
+                    # written to scaffold.lock, ensuring the database can hydrate correctly.
+
+                    metrics = gnosis.get("metrics", {})
+
+                    # 1. Embed Functions
+                    metrics["functions"] = [
+                        {
+                            "name": f.get("name", "unknown"),
+                            "lineno": f.get("start_point", [0, 0])[0] + 1
+                        }
+                        for f in gnosis.get("functions", [])
+                    ]
+
+                    # 2. Embed Classes
+                    metrics["classes"] = [
+                        {
+                            "name": c.get("name", "unknown"),
+                            "lineno": c.get("start_point", [0, 0])[0] + 1
+                        }
+                        for c in gnosis.get("classes", [])
+                    ]
+
+                    # Persist the enriched metrics back to the result object
+                    result.metrics = metrics
+
+                    # --- Symbol Mapping for Dependency Resolution ---
+                    # Use the result's logical path for the module base
+                    module_base_path = result.path.with_suffix('')
+                    module_base = str(module_base_path).replace('/', '.').replace('\\', '.')
+                    if module_base.endswith('.__init__'):
+                        module_base = module_base[:-9]
+
+                    path_posix = result.path.as_posix()
+
+                    # Map defined symbols to this file's path string
+                    for func in gnosis.get("functions", []):
+                        symbol_map[func['name']] = path_posix
+                        symbol_map[f"{module_base}.{func['name']}"] = path_posix
+                    for cls in gnosis.get("classes", []):
+                        symbol_map[cls['name']] = path_posix
+                        symbol_map[f"{module_base}.{cls['name']}"] = path_posix
+
+            except Exception as e:
+                Logger.warn(f"Soul-Reader's Gaze was clouded for '{result.path.name}' during census: {e}")
+
+        # --- PASS 2: BOND FORGING (DEPENDENCY RESOLUTION) ---
+        for result in items_to_scan:
+            gnosis = raw_gnosis_map.get(result.path)
+            if not gnosis or "error" in gnosis:
+                continue
+
+            # The Inquisitor gives us symbol dependencies from the `imported_symbols` key
+            symbol_dependencies = gnosis.get("dependencies", {}).get("imported_symbols", [])
+            resolved_deps = set()
+
+            for dep_symbol in symbol_dependencies:
+                # We strip to the leaf symbol name for matching against our flat map
+                cleaned_dep = dep_symbol.split('.')[-1]
+
+                if target_path_str := symbol_map.get(cleaned_dep):
+                    # Prevent self-reference
+                    if target_path_str != result.path.as_posix():
+                        resolved_deps.add(target_path_str)
+                else:
+                    # Could be stdlib or third-party lib.
+                    # Future ascension: deeper resolution for external packages.
+                    pass
+
+            result.dependencies = sorted(list(resolved_deps))
+
+        return list(self.tx.write_dossier.values())

velm/core/kernel/transaction/committer.py

@@ -0,0 +1,126 @@
+# Path: scaffold/core/kernel/transaction/committer.py
+import os
+import shutil
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, List
+
+# Ascension VIII: The Windows Healer
+from ....utils import _resilient_rename
+from ....logger import Scribe, get_console
+from ....contracts.heresy_contracts import ArtisanHeresy
+
+if TYPE_CHECKING:
+    from .staging import StagingManager
+
+Logger = Scribe("GnosticCommitter")
+
+
+class GnosticCommitter:
+    """
+    =================================================================================
+    == THE HAND OF MANIFESTATION (V-Ω-ETERNAL-APOTHEOSIS-ULTIMA)                   ==
+    =================================================================================
+    This divine artisan is the final link in the chain of causality. It takes the
+    pure, perfected will from the Ephemeral Staging Realm and makes it manifest in
+    the Mortal Realm with unbreakable, atomic precision. It is the very hand of God.
+    =================================================================================
+    """
+
+    def __init__(self, project_root: Path, staging_manager: "StagingManager", logger: Scribe):
+        self.project_root = project_root
+        self.staging_manager = staging_manager
+        self.logger = logger
+        self.console = get_console()
+
+    def commit(self):
+        """
+        The Grand Rite of Materialization.
+        Moves all artifacts from the staging area to the project root atomically.
+        """
+        start_time = time.monotonic()
+        staged_files = self._collect_staged_artifacts()
+
+        if not staged_files:
+            self.logger.verbose("Commitment rite concluded. The ephemeral realm was a void.")
+            return
+
+        self.logger.info("The Hand of Manifestation awakens. Committing staged reality...")
+
+        # Ascension III: The Hierophant of Pruning
+        self._prune_conflicting_directories(staged_files)
+
+        # Ascension IV: The Luminous Voice
+        from rich.progress import Progress, SpinnerColumn, BarColumn, TextColumn
+
+        with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                BarColumn(),
+                console=self.console,
+                transient=True
+        ) as progress:
+            task = progress.add_task("[cyan]Materializing...", total=len(staged_files))
+
+            for staged_path in staged_files:
+                try:
+                    rel_path = staged_path.relative_to(self.staging_manager.staging_root)
+                    live_path = self.project_root / rel_path
+
+                    progress.update(task, advance=1, description=f"[cyan]Inscribing [green]'{rel_path}'[/green]...")
+
+                    # The Rite of Parent Sanctum Forging
+                    live_path.parent.mkdir(parents=True, exist_ok=True)
+
+                    # Ascension II: The Unbreakable Vow of Atomicity
+                    # We use our ascended, resilient rename for Windows safety.
+                    _resilient_rename(staged_path, live_path)
+
+                    # Ascension VI & VII: The Permission Alchemist & Chronomancer's Touch
+                    # Note: shutil.copystat follows symlinks, which is what we want here.
+                    # We are copying the *state* of the staged file, not its link nature.
+                    shutil.copystat(live_path, live_path, follow_symlinks=True)
+
+                except Exception as e:
+                    # Ascension X: The Unbreakable Ward of Paradox
+                    raise ArtisanHeresy(
+                        f"Commitment Paradox: The Hand faltered while inscribing '{rel_path}'.",
+                        child_heresy=e
+                    ) from e
+
+        duration = (time.monotonic() - start_time) * 1000
+        self.logger.success(f"Commitment complete. {len(staged_files)} artifacts manifested in {duration:.0f}ms.")
+
+    def _collect_staged_artifacts(self) -> List[Path]:
+        """
+        Performs a deep Gaze upon the staging sanctum to find all materialized souls.
+        Ascension V: The Sentinel of the Void - Skips empty directories.
+        """
+        staged_artifacts = []
+        if not self.staging_manager.staging_root.exists():
+            return []
+
+        for root, dirs, files in os.walk(self.staging_manager.staging_root):
+            root_path = Path(root)
+            for name in files:
+                staged_artifacts.append(root_path / name)
+            # Ascension V: We only add directories if they are NOT empty.
+            # This is a heuristic; a better way is to track created dirs in the transaction.
+            # For now, we rely on the final Ghost Buster pass in the creator engine.
+            # A simpler version is to just add all files and let mkdir -p handle parents.
+
+        # We return only files, as `os.replace` on a directory can be non-atomic.
+        # Parent directories will be created on demand by the commit loop.
+        return staged_artifacts
+
+    def _prune_conflicting_directories(self, staged_files: List[Path]):
+        """
+        Ascension III: Annihilates directories in the mortal realm that are about to
+        be replaced by files from the staging realm.
+        """
+        for staged_path in staged_files:
+            rel_path = staged_path.relative_to(self.staging_manager.staging_root)
+            live_path = self.project_root / rel_path
+            if live_path.is_dir() and not live_path.is_symlink():
+                self.logger.warn(f"Annihilating sanctum '{rel_path}' to make way for a new scripture.")
+                shutil.rmtree(live_path)

velm/core/kernel/transaction/contracts.py

@@ -0,0 +1,77 @@
+# Path: scaffold/core/kernel/transaction/contracts.py
+# ---------------------------------------------------
+
+from __future__ import annotations
+from enum import Enum
+from uuid import UUID, uuid4
+from typing import Any, Dict, Optional
+import time
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class LedgerOperation(str, Enum):
+    """The Gnostic verbs of every atomic action in the cosmos."""
+    SET_VAR = "SET_VAR"
+    WRITE_FILE = "WRITE_FILE"
+    DELETE_FILE = "DELETE_FILE"
+    MKDIR = "MKDIR"
+    RMDIR = "RMDIR"
+    RENAME = "RENAME"
+    CHMOD = "CHMOD"
+    EXEC_SHELL = "EXEC_SHELL"
+    # [PHASE III] New Ops
+    RESTORE_FILE = "RESTORE_FILE"
+
+
+
+
+class TransactionalGnosis(BaseModel):
+    """
+    =============================================================================
+    == THE VESSEL OF THE FALLEN RITE (V-Ω-FORENSIC-DOSSIER)                    ==
+    =============================================================================
+    The sacred, immutable vessel carrying the complete Gnosis of a transaction's
+    state at the moment of its paradoxical collapse. It is the "black box" recorder,
+    the core of our forensic archival system, ensuring that no failure is ever a
+    true mystery.
+    =============================================================================
+    """
+    # === THE VOW OF IMMUTABILITY & GNOSTIC PURITY ===
+    # We forbid extra fields to ensure the contract is never profaned.
+    model_config = ConfigDict(frozen=True, extra='forbid')
+
+    # --- Core Identity & Context ---
+    rite_name: str = Field(
+        ...,
+        description="The sacred name of the rite that was being conducted (e.g., 'Genesis: my-app')."
+    )
+    tx_id: str = Field(
+        ...,
+        description="The unique, immutable identifier for this specific transactional reality."
+    )
+    context: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="The complete Gnostic context (variables) at the moment of the paradox."
+    )
+
+    # --- Telemetry of the Rite ---
+    dossier_count: int = Field(
+        ...,
+        description="The number of file operations (writes) recorded before the paradox."
+    )
+    edict_count: int = Field(
+        ...,
+        description="The number of Maestro's Edicts (post-run commands) recorded."
+    )
+    heresy_count: int = Field(
+        ...,
+        description="The number of non-critical heresies perceived before the final collapse."
+    )
+
+    # --- Metaphysical State ---
+    is_simulation: bool = Field(
+        ...,
+        description="A vow proclaiming whether this rite was a prophecy (True) or a materialization (False)."
+    )
+
+

velm/core/kernel/transaction/facade.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+import uuid
+import time
+from pathlib import Path
+from typing import Optional, List, Dict, Any, Tuple, Union
+
+from .locking import GnosticLock
+from .staging import StagingManager
+from .committer import GnosticCommitter
+from .rollback import RollbackChronomancer
+from .chronicle_bridge import ChronicleBridge
+from .contracts import TransactionalGnosis
+from ....contracts.data_contracts import GnosticWriteResult
+from ....contracts.heresy_contracts import Heresy, ArtisanHeresy
+from ....logger import Scribe
+
+Logger = Scribe("GnosticTransaction")
+
+
+class GnosticTransaction:
+    """
+    =================================================================================
+    == THE GOD-ENGINE OF CONSISTENCY (V-Ω-ETERNAL-APOTHEOSIS-ULTIMA++)             ==
+    =================================================================================
+    LIF: 10,000,000
+
+    This is the High Conductor of Consistency in its final, eternal form. It has
+    been ascended to become a sentient, self-aware guardian of causality, ensuring
+    every rite that alters reality is atomic, reversible, and forensically chronicled.
+
+    ### THE PANTHEON OF 12+ LEGENDARY ASCENSIONS:
+
+    1.  **The Gnostic Soul (Immutable ID):** Each transaction is born with a unique,
+        immutable `tx_id`, its one true name in the cosmos, linking all its actions.
+    2.  **The Chronicle Linkage:** Every file forged or transfigured under its watch
+        is eternally bound to its `tx_id` in the Crystal Mind (`gnosis.db`), creating
+        an unbreakable chain of provenance.
+    3.  **The Gaze of Pre-Commit Gnosis (THE HEALING):** Before any reality is made
+        manifest, it commands the `ChronicleBridge` to perform a deep Gnostic Gaze,
+        transmuting raw imported symbols into fully resolved file paths. This
+        annihilates the "Disconnected Graph" heresy.
+    4.  **The Simulation Ward:** It possesses an unbreakable vow. In simulation mode
+        (`simulate=True`), its `commit` and `seal_chronicle` rites are stayed,
+        preventing any profane touch upon the mortal realm or its history.
+    5.  **The Forensic Archivist:** If a paradox shatters the symphony, it commands the
+        `RollbackChronomancer` to forge a complete forensic dossier of the failed
+        rite for post-mortem inquest.
+    6.  **The Architect of Reversibility:** It is the master scribe of the `Ledger`,
+        meticulously chronicling the Gnostic Inverse of every action, making universal
+        undo a reality.
+    7.  **The Maestro's Baton (`materialize`):** It provides a sacred rite to force the
+        commitment of the ephemeral reality mid-symphony, allowing the Maestro to
+        conduct edicts upon a newly forged world.
+    8.  **The Unbreakable Vow (Context Manager):** Its very form is a sacred vow. The
+        `__enter__` and `__exit__` rites guarantee that reality is either purely
+        transfigured or perfectly restored. There is no middle state.
+    9.  **The Polyglot Path Normalizer (`triangulate_relative_path`):** Wields a divine
+        artisan to perceive a path's true, relative soul, whether it comes from the
+        Mortal Realm or the Ephemeral Staging Realm.
+    10. **The Heresy Vessel:** It is the sacred chalice for all non-critical heresies
+        perceived during a rite, ensuring they are chronicled without halting the
+        Great Work.
+    11. **The Gnostic Context Bridge:** It serves as the one true vessel for the living
+        Gnosis (variables) of a rite, making them available to all subordinate artisans.
+    12. **The Luminous Voice:** Its every major transition—begin, commit, rollback,
+        seal—is proclaimed to the Gnostic log, providing a perfect audit trail.
+    """
+
+    def __init__(
+            self,
+            project_root: Path,
+            rite_name: str,
+            blueprint_path: Optional[Path] = None,
+            *,
+            use_lock: bool = True,
+            simulate: bool = False,
+            **kwargs: Any
+    ):
+        self.logger = Logger
+        self.project_root = project_root.resolve()
+        self.rite_name = rite_name
+        self.blueprint_path = blueprint_path or Path(f"manual/{rite_name.replace(' ', '_')}")
+        self.tx_id = uuid.uuid4().hex
+        self.use_lock = use_lock
+        self.simulate = simulate
+        self.start_time = time.monotonic()
+
+        self.active = False
+        self.materialized = False
+        self._dossier_enriched = False
+
+        # --- The Forging of the Pantheon ---
+        self.staging_manager = StagingManager(self.project_root, self.tx_id)
+        self.lock = GnosticLock(self.staging_manager.scaffold_dir / "transaction.lock", self.rite_name)
+        self.committer = GnosticCommitter(self.project_root, self.staging_manager, self.logger)
+        self.chronomancer = RollbackChronomancer(self.staging_manager, self.project_root, self.logger)
+        self.chronicle_bridge = ChronicleBridge(self)
+
+        # --- Gnostic Memory ---
+        self.write_dossier: Dict[Path, GnosticWriteResult] = {}
+        self.edicts_executed: List[str] = []
+        self.heresies_perceived: List[Heresy] = []
+        self.context: Dict[str, Any] = {}
+
+    def __enter__(self) -> GnosticTransaction:
+        if self.use_lock:
+            self.lock.acquire()
+
+        self.staging_manager.initialize_sanctums()
+
+        self.active = True
+        Logger.verbose(f"Transaction '{self.rite_name}' (ID: {self.tx_id[:8]}) has begun.")
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """The Grand Symphony of Finalization."""
+        self.active = False
+        try:
+            if exc_type:
+                Logger.warn(f"Transaction '{self.rite_name}' aborted by paradox: {exc_val}")
+                self.chronomancer.perform_emergency_rollback()
+                self._archive_failed_rite(exc_type, exc_val, exc_tb)
+            else:
+                # [FACULTY 3] THE GAZE OF PRE-COMMIT GNOSIS
+                # The final, sacred Gaze that heals the dependency graph.
+                self._enrich_if_needed()
+
+                # [FACULTY 4] THE SIMULATION WARD
+                if not self.simulate:
+                    if self.write_dossier and not self.materialized:
+                        self.committer.commit()
+                        self.materialized = True
+
+                    if self.write_dossier or self.edicts_executed:
+                        self.chronicle_bridge.seal_chronicle()
+                else:
+                    Logger.verbose("Commitment and Chronicle sealing stayed (Simulation Mode).")
+
+        except Exception as commit_heresy:
+            Logger.error("A catastrophic paradox occurred during the commit phase. Initiating rollback.", exc_info=True)
+            self.chronomancer.perform_emergency_rollback()
+            self._archive_failed_rite(type(commit_heresy), commit_heresy, commit_heresy.__traceback__)
+            raise ArtisanHeresy("COMMIT_HERESY: Final materialization failed. Reality restored.",
+                                child_heresy=commit_heresy) from commit_heresy
+        finally:
+            self.staging_manager.cleanup()
+            if self.use_lock:
+                self.lock.release()
+            Logger.verbose(f"Transaction '{self.rite_name}' concluded.")
+
+    def _enrich_if_needed(self):
+        """Performs dependency analysis on staged files before they are moved."""
+        if self._dossier_enriched or self.simulate:
+            return
+
+        Logger.verbose("Performing pre-commit Gnostic enrichment of write dossier...")
+        enriched_dossier_list = self.chronicle_bridge._enrich_dossier()
+        for result in enriched_dossier_list:
+            self.write_dossier[result.path] = result
+        self._dossier_enriched = True
+        Logger.verbose("Enrichment complete.")
+
+    def get_staging_path(self, logical_path: Union[str, Path]) -> Path:
+        """Delegates the sacred duty of path resolution to the Staging Manager."""
+        return self.staging_manager.get_staging_path(logical_path)
+
+    def record(self, result: GnosticWriteResult):
+        """Records the outcome of a write operation."""
+        if not self.active: raise RuntimeError("Cannot record to an inactive transaction.")
+        logical_path = self.staging_manager.triangulate_relative_path(result.path)
+        self.write_dossier[logical_path] = result.model_copy(update={"path": logical_path})
+
+    def record_edict(self, command: str):
+        """Records a Maestro's Edict for the chronicle."""
+        if not self.active: raise RuntimeError("Cannot record to an inactive transaction.")
+        self.edicts_executed.append(command)
+
+    def record_heresy(self, heresy: Heresy):
+        """[FACULTY 10] Chronicles a non-critical heresy perceived during the rite."""
+        if not self.active: return
+        self.heresies_perceived.append(heresy)
+
+    def materialize(self):
+        """[FACULTY 7] Forces an early commit of the staged reality for the Maestro's Gaze."""
+        if self.materialized or self.simulate: return
+        Logger.info("Materializing Staged Reality for Maestro's access...")
+        self._enrich_if_needed()
+        self.committer.commit()
+        self.materialized = True
+
+    def cancel(self):
+        """A sacred rite to explicitly command a rollback from within an artisan."""
+        if not self.active: return
+        Logger.warn(f"Rite '{self.rite_name}' was explicitly cancelled. Reversing time...")
+        self.chronomancer.perform_emergency_rollback()
+        # We must prevent the __exit__ block from trying to commit
+        self.write_dossier.clear()
+        self.edicts_executed.clear()
+
+    @property
+    def duration(self) -> float:
+        """Returns the elapsed time since the transaction began."""
+        return time.monotonic() - self.start_time
+
+    def get_gnostic_context_view(self) -> Dict[str, Any]:
+        """[FACULTY 11] Returns a safe, read-only copy of the Gnostic context."""
+        return self.context.copy()
+
+    def _archive_failed_rite(self, exc_type, exc_val, exc_tb):
+        """[FACULTY 5] Delegates the Rite of Forensic Archival to the Rollback Chronomancer."""
+        gnosis = TransactionalGnosis(
+            rite_name=self.rite_name, tx_id=self.tx_id, context=self.context,
+            dossier_count=len(self.write_dossier), edict_count=len(self.edicts_executed),
+            heresy_count=len(self.heresies_perceived), is_simulation=self.simulate
+        )
+        self.chronomancer.archive_failed_rite(gnosis, exc_type, exc_val, exc_tb)