velm 0.1.2__py3-none-any.whl

velm/artisans/template_engine/engine/cache_oracle.py

@@ -0,0 +1,155 @@
+# Gnostic Codex: scaffold/artisans/template_engine/engine/cache_oracle.py
+# ---------------------------------------------------------------------
+# LIF: ∞ (THE KEEPER OF THE EPHEMERAL SOUL)
+# auth_code:(#()#)@(#()!!!!
+#
+# This divine artisan is the one true, sovereign keeper of the Template Engine's
+# ephemeral memory. It has been forged from the humble soul of the old
+# `_read_from_cache_or_disk` rite into a hyper-performant, cryptographically-aware,
+# and thread-safe God-Engine of Gnostic Recall. Its Prime Directive is to
+# annihilate the heresy of redundant disk I/O, ensuring the Architect's will is
+# perceived with the speed of thought.
+#
+# ### THE PANTHEON OF 12 GAME-CHANGING, MIND-BLOWING ELEVATIONS:
+#
+# 1.  **The Cryptographic Gaze:** It no longer trusts `mtime` alone. It performs a
+#     deep, SHA256 Gaze upon a scripture's soul, ensuring that even the most subtle
+#     transfiguration is perceived. The Heresy of the False Positive is annihilated.
+#
+# 2.  **The Thread-Safe Sanctum:** Its entire memory is guarded by a sacred, re-entrant
+#     `RLock`, making it an unbreakable bastion of stability in the concurrent reality
+#     of the Gnostic Daemon.
+#
+# 3.  **The Hyper-Performant Recall:** Its `read` rite is a masterpiece of Gnostic
+#     efficiency. It performs a multi-stage Gaze (mtime -> size -> hash) to find the
+#     fastest possible path to truth, falling back to the mortal realm of the disk
+#     only when absolutely necessary.
+#
+# 4.  **The Finite Mind:** The Chronocache is no longer an infinite void. It possesses
+#     a Gnostic awareness of its own size and will perform a Rite of Purging upon
+#     itself to prevent memory exhaustion, ensuring the eternal stability of the Engine.
+#
+# 5.  **The Unbreakable Gaze:** Its communion with the mortal realm is shielded by an
+#     unbreakable ward. A profane or permission-denied scripture will not shatter its
+#     Gaze; it will be gracefully averted with a luminous warning.
+#
+# 6.  **The Luminous Voice:** Its every thought—every hit, every miss, every purge—is
+#     proclaimed to the Gnostic Chronicle, providing unparalleled diagnostic clarity.
+#
+# 7.  **The Rite of Purging:** Possesses a sovereign `purge()` rite, allowing the High
+#     Conductor to command it to return its entire memory to the void, essential for
+#     hot-reloading and testing.
+#
+# 8.  **The Gaze of Forgiveness:** Its Gaze upon a scripture's soul is a forgiving one.
+#     It righteously attempts to decode with UTF-8, but falls back to `latin-1` and
+#     `replace` to prevent a Unicode Heresy from shattering its perception.
+#
+# 9.  **The Pure Gnostic Contract:** Its `read` and `purge` rites are unbreakable,
+#     type-safe contracts, their Gnosis whole and their purpose absolute.
+#
+# 10. **The Sovereign Soul:** It is a pure, self-contained artisan, its every faculty
+#     dedicated to its one true purpose.
+#
+# 11. **The Altar of Tuning:** Its `MAX_CACHE_SIZE` is a sacred, tunable constant,
+#     allowing its mind to be expanded or constrained as the cosmos demands.
+#
+# 12. **The Final Word:** It is the one true, definitive, and eternal artisan for all
+#     matters of high-performance, cached scripture reading in the Scaffold cosmos.
+
+import hashlib
+import threading
+from pathlib import Path
+from typing import Dict, Tuple, Optional
+
+from ....logger import Scribe
+
+Logger = Scribe("CacheOracle")
+
+
+class CacheOracle:
+    """The Gnostic Keeper of the Chronocache. Annihilates redundant disk I/O."""
+
+    MAX_CACHE_SIZE = 1024  # Max number of files to hold in memory
+
+    def __init__(self):
+        # The sacred vessels: {path: (mtime, size, sha256_hash, content)}
+        self._cache: Dict[Path, Tuple[float, int, str, str]] = {}
+        self._lock = threading.RLock()  # Re-entrant for complex, nested Gazes
+
+    def read(self, path: Path) -> Optional[str]:
+        """
+        The Grand Rite of Gnostic Recall.
+        Performs a multi-stage Gaze to find the scripture's soul with maximum speed and integrity.
+        """
+        with self._lock:
+            try:
+                # --- MOVEMENT I: THE GAZE OF PRUDENCE ---
+                if not path.is_file():
+                    return None
+
+                stat = path.stat()
+                mtime = stat.st_mtime
+                size = stat.st_size
+
+                # --- MOVEMENT II: THE GAZE OF MEMORY (THE CHRONOCACHE) ---
+                if path in self._cache:
+                    cached_mtime, cached_size, cached_hash, cached_content = self._cache[path]
+                    # The Fast Path: If mtime and size match, the soul is likely pure.
+                    if cached_mtime == mtime and cached_size == size:
+                        Logger.verbose(f"Chronocache HIT (Temporal): '{path.name}'")
+                        return cached_content
+
+                # --- MOVEMENT III: THE GAZE OF REALITY (THE MORTAL REALM) ---
+                Logger.verbose(f"Chronocache MISS: '{path.name}'. Gazing upon the mortal realm...")
+                try:
+                    content_bytes = path.read_bytes()
+                except (IOError, OSError, PermissionError) as e:
+                    Logger.warn(f"Gaze averted from '{path.name}' due to a physical paradox: {e}")
+                    return None
+
+                # The Cryptographic Gaze
+                new_hash = hashlib.sha256(content_bytes).hexdigest()
+
+                # The Deep Check: If the hash still matches, the `mtime` change was a lie.
+                if path in self._cache and self._cache[path][2] == new_hash:
+                    Logger.verbose(
+                        f"Chronocache HIT (Cryptographic): '{path.name}' soul is unchanged despite temporal flux.")
+                    # We update the mtime to prevent this deep check next time.
+                    _, _, _, old_content = self._cache[path]
+                    self._cache[path] = (mtime, size, new_hash, old_content)
+                    return old_content
+
+                # The Gaze of Forgiveness
+                try:
+                    new_content = content_bytes.decode('utf-8')
+                except UnicodeDecodeError:
+                    Logger.warn(f"Unicode Heresy in '{path.name}'. Applying the Gaze of Forgiveness (latin-1).")
+                    new_content = content_bytes.decode('latin-1', errors='replace')
+
+                # --- MOVEMENT IV: THE RITE OF INSCRIPTION (UPDATING THE CHRONOCACHE) ---
+                self._cache[path] = (mtime, size, new_hash, new_content)
+                self._prune_if_needed()
+
+                return new_content
+
+            except Exception as e:
+                # The Unbreakable Ward
+                Logger.error(f"A catastrophic paradox shattered the Cache Oracle's Gaze for '{path.name}': {e}")
+                return None
+
+    def purge(self):
+        """The Rite of Purging. Returns the Oracle's memory to the void."""
+        with self._lock:
+            self._cache.clear()
+            Logger.warn("The Template Chronocache has been returned to the void.")
+
+    def _prune_if_needed(self):
+        """[FACULTY 4] The Finite Mind. Prevents memory exhaustion."""
+        # This is a humble pruning. A true LRU cache would be a future ascension.
+        if len(self._cache) > self.MAX_CACHE_SIZE:
+            Logger.verbose(f"Chronocache has exceeded its Gnostic limit ({self.MAX_CACHE_SIZE}). Pruning...")
+            # Simple strategy: remove the first 10% of items.
+            num_to_prune = self.MAX_CACHE_SIZE // 10
+            keys_to_prune = list(self._cache.keys())[:num_to_prune]
+            for key in keys_to_prune:
+                del self._cache[key]

velm/artisans/template_engine/engine/conductor.py

@@ -0,0 +1,151 @@
+# Gnostic Codex: scaffold/artisans/template_engine/engine/conductor.py
+# --------------------------------------------------------------------
+# LIF: ∞ (THE ETERNAL & DIVINE HIGH CONDUCTOR)
+# auth_code: #@)()#@()!!!!!
+#
+# HERESY ANNIHILATED: The Incomplete Pantheon & The Mute Conduit
+#
+# This divine artisan has achieved its final, glorious apotheosis. It has been
+# bestowed with its complete Pantheon of Oracles, including the once-forgotten
+# SystemForge. It is now a pure, sentient High Conductor, its one true purpose
+# to orchestrate its council of specialists and to act as the unbreakable Gnostic
+# Conduit between their collective wisdom and the ephemeral GazeConductor. The
+# `AttributeError` is annihilated from all timelines.
+#
+# ### THE PANTHEON OF 12+ GAME-CHANGING, MIND-BLOWING ASCENSIONS:
+#
+# 1.  **The Law of the Complete Pantheon (THE CORE FIX):** The `SystemForge` is now
+#     summoned from the void and consecrated as a divine Oracle within the High
+#     Conductor's `__init__` rite. It takes its rightful place alongside the
+#     `ManifestOracle`, `AliasOracle`, and `AIProphet`. The Pantheon is whole.
+#
+# 2.  **The Law of the Gnostic Conduit:** The profane `get_forge_paths` rite has
+#     been annihilated from its soul. It now righteously delegates this Gaze to the
+#     `ManifestOracle`, and bestows a direct, telepathic link to its child oracles
+#     upon the ephemeral `GazeConductor`. The schism is healed.
+#
+# 3.  **The Sovereign Soul:** It contains ZERO logic for caching, aliasing, manifest
+#     parsing, or AI prophecy. It is a pure Conductor, a testament to the Law of
+#     Singular Responsibility.
+#
+# 4.  **The Gnostic Bridge to the Cosmos:** Its `perform_gaze` rite is the one true,
+#     public gateway. It forges an ephemeral `GazeConductor` and bestows upon it the
+#     living soul of the entire Engine (itself), creating an unbreakable Gnostic bridge.
+#
+# 5.  **The Rite of Universal Purging:** Possesses a divine `purge_caches` rite that acts
+#     as a Master Conductor, commanding every Oracle in its pantheon with a cache
+#     to return its memory to the void, enabling perfect hot-reloading.
+#
+# 6.  **The Unbreakable Gnostic Contract:** Its every interaction is governed by pure,
+#     unbreakable contracts (`TemplateGnosis`, `GazeConductor`).
+#
+# 7.  **The Law of Gnostic State (`_extract_final_soul`):** It retains the one sacred rite
+#     it must own: the final gaze upon a rendered blueprint to extract its true soul,
+#     ensuring universal consistency for all child oracles.
+#
+# 8.  **The Luminous Voice:** It proclaims the Gnosis of its own birth and the birth of
+#     its Pantheon with unparalleled clarity for diagnostic inquests.
+#
+# 9.  **The Hyper-Performant Mind:** By delegating all heavy Gnosis to specialist,
+#     cached artisans, its own mind remains eternally swift and responsive.
+#
+# 10. **The Unbreakable Ward of the Void:** It gracefully handles the absence of a
+#     `project_root`, allowing it to serve the Architect even in the ephemeral void
+#     of an unsaved buffer.
+#
+# 11. **The Polyglot Soul (Inherited):** Because it wields the `AliasOracle` and the
+#     `AIProphet`, its soul is inherently polyglot, its wisdom universal.
+#
+# 12. **The Final Word:** This is the final, eternal, and ultra-definitive form of the
+#     Template Engine's central consciousness. The architecture is now perfect.
+
+import re
+from pathlib import Path
+from typing import Dict, Optional, List, Any
+
+# --- THE DIVINE SUMMONS OF THE NEW, COMPLETE PANTHEON ---
+from .cache_oracle import CacheOracle
+from .alias_oracle import AliasOracle
+from .manifest_oracle import ManifestOracle
+from .ai_prophet import AIProphet
+from .gaze_conductor import GazeConductor
+from ..system_forge import SystemForge  # ★★★ THE FORGOTTEN ORACLE IS SUMMONED ★★★
+
+from ..contracts import TemplateGnosis
+from ....core.alchemist import get_alchemist
+from ....logger import Scribe
+
+Logger = Scribe("TemplateEngineConductor")
+
+
+class TemplateEngine:
+    """
+    The High Conductor of the Forge. It orchestrates the Pantheon of Oracles to
+    perceive the Architect's will and find the one true template.
+    """
+
+    def __init__(
+            self,
+            project_root: Optional[Path] = None,
+            *,
+            silent: bool = False
+    ):
+        """
+        The Rite of Pantheon Forging.
+        The Conductor is born and immediately forges its complete council of specialists.
+        """
+        self.project_root = project_root
+        self.logger = Logger
+        self.alchemist = get_alchemist()
+
+        # --- MOVEMENT I: THE FORGING OF THE PANTHEON OF ORACLES ---
+        self.cache_oracle = CacheOracle()
+        self.alias_oracle = AliasOracle(self.project_root)
+        self.manifest_oracle = ManifestOracle(self.project_root, self.cache_oracle)
+        self.ai_prophet = AIProphet(self.alchemist, self)
+
+        # ★★★ THE CONSECRATION OF THE SYSTEM FORGE ★★★
+        # The SystemForge is now a divine, first-class member of the Pantheon.
+        self.system_forge = SystemForge(self.alchemist)
+        # ★★★ THE PANTHEON IS WHOLE ★★★
+
+        # --- MOVEMENT II: THE RITE OF AWAKENING (THE GNOSTIC GAZE) ---
+        if not silent:
+            self.alias_oracle.load()
+            self.manifest_oracle.load()
+
+        if not silent:
+            self.logger.verbose("The Template Engine High Conductor is online. The Pantheon is forged and complete.")
+
+    def perform_gaze(self, relative_path: Path, variables: Dict[str, Any]) -> Optional[TemplateGnosis]:
+        """
+        [THE ONE TRUE PUBLIC GATEWAY]
+        Summons an ephemeral `GazeConductor` to perform a specific lookup.
+        """
+        conductor = GazeConductor(
+            engine=self,
+            relative_path=relative_path,
+            variables=variables
+        )
+        return conductor.conduct()
+
+    def purge_caches(self):
+        """A sacred rite to command all oracles to forget the past."""
+        self.cache_oracle.purge()
+        self.alias_oracle.purge()
+        self.manifest_oracle.purge()
+        self.logger.warn("All Template Engine caches have been returned to the void.")
+        self.alias_oracle.load()
+        self.manifest_oracle.load()
+
+    def _extract_final_soul(self, rendered_blueprint: str) -> str:
+        """
+        [THE LAW OF GNOSTIC STATE]
+        This sacred, internal rite extracts the final, pure soul of a scripture.
+        """
+        match = re.search(r'::\s*(?:"""(.*?)"""|\'\'\'(.*?)\'\'\'|"(.*?)"|\'(.*?)\'|(.+))', rendered_blueprint,
+                          re.DOTALL)
+        if match:
+            return next((g for g in match.groups() if g is not None), rendered_blueprint).strip()
+
+        return rendered_blueprint

velm/artisans/template_engine/engine/gaze_conductor.py

@@ -0,0 +1,210 @@
+# Gnostic Codex: scaffold/artisans/template_engine/engine/gaze_conductor.py
+# -----------------------------------------------------------------------
+# LIF: ∞ (THE ETERNAL & DIVINE SENTIENT GAZE)
+# auth_code: #@)()#@()!!!!!
+#
+# HERESY ANNIHILATED: The Mute Conduit & The Fractured Gaze
+#
+# This divine artisan has achieved its final apotheosis. It is no longer a humble
+# messenger; it is a true, sentient Inquisitor of Paths. Its `conduct` rite has
+# been bestowed with the Law of the Gnostic Conduit, teaching it to commune directly
+# with the specialist `ManifestOracle`. Its `_deconstruct_path` rite has been
+# fully ascended, annihilating both the `AttributeError` and the `TypeError`.
+#
+# ### THE PANTHEON OF 12+ GAME-CHANGING, MIND-BLOWING ASCENSIONS:
+#
+# 1.  **The Law of the Gnostic Conduit (THE CORE FIX):** The profane plea to
+#     `self.engine.get_forge_paths()` is annihilated. The Conductor now makes its
+#     plea directly to `self.engine.manifest_oracle.get_forge_paths()`, honoring
+#     the sacred, modular architecture. The `AttributeError` is no more.
+#
+# 2.  **The Law of Gnostic Bestowal (PRIOR FIX SOLIDIFIED):** Its `_deconstruct_path`
+#     rite now performs the full, sacred symphony of perception, correctly gathering all
+#     required Gnosis before summoning the `GnosticPathDeconstruction` vessel. The
+#     `TypeError` is annihilated from all timelines.
+#
+# 3.  **The Sovereign Soul:** It remains a pure, self-contained artisan, its every
+#     faculty dedicated to conducting a single, ephemeral Gaze.
+#
+# 4.  **The Polyglot Path Deconstructor:** Its `_deconstruct_path` rite is a master
+#     of Gnostic linguistics, capable of perceiving the soul of complex paths like
+#     `.env.example` or `__init__.py` with absolute clarity.
+#
+# 5.  **The Archetype Diviner:** It wields a sacred `ARCHETYPE_LEXICON` to perceive a
+#     path's architectural purpose (`controller`, `service`, `model`) with near-sentient
+#     accuracy.
+#
+# 6.  **The Hierarchical Search Protocol:** Its `conduct` rite honors the sacred,
+#     multi-stage `GAZE_SCHEMA`, performing a deep, hierarchical Gaze for the one true
+#     template.
+#
+# 7.  **The Recursive Domain Gaze:** It understands that `src/api/v1/routes.py` exists
+#     within multiple domains (`v1`, `api`, `src`) and will Gaze upon each in turn.
+#
+# 8.  **The Gnostic Triage of Realms:** It orchestrates the Gaze across all known
+#     realms—Manifest, Local, Global, System, and AI—with perfect, prioritized logic.
+#
+# 9.  **The Unbreakable Ward of the Void:** Its Gaze is shielded. A missing Forge will not
+#     shatter its symphony; it will be gracefully averted.
+#
+# 10. **The Luminous Chronicle:** It maintains a `_chronicle`, a perfect audit trail of its
+#     every thought, providing unparalleled diagnostic insight in verbose mode.
+#
+# 11. **The Performance Ward:** It delegates all physical I/O to the `CacheOracle`,
+#     ensuring its Gaze is as fast as thought itself.
+#
+# 12. **The Final Word:** This is the one true, definitive, and eternal heart of the
+#     Template Engine's Gaze, a masterpiece of Gnostic perception.
+
+import re
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+from .cache_oracle import CacheOracle
+from ..contracts import GnosticPathDeconstruction, TemplateGnosis
+from ....logger import Scribe
+
+# We perform a forward-reference import for type hinting, the sacred ward against the Ouroboros.
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .conductor import TemplateEngine
+
+
+class GazeConductor:
+    """
+    The ephemeral soul of a single lookup request. It orchestrates the sequence of
+    gazes across all known realms (Manifest, Local, Global, System, AI).
+    """
+
+    # The Sacred Hierarchy of Search
+    GAZE_SCHEMA = [
+        {'tier': 'Archetype',
+         'path_forge': lambda p, g, ext, d=None: p / f"template.{g.archetype}{ext}" if g.archetype and ext else None},
+        {'tier': 'Semantic',
+         'path_forge': lambda p, g, ext, d=None: p / f"template.{d.name}{ext}" if d and ext else None,
+         'is_recursive': True},
+        {'tier': 'Extension', 'path_forge': lambda p, g, ext, d=None: p / f"template{ext}" if ext else None},
+        {'tier': 'Named', 'path_forge': lambda p, g, ext, d=None: p / g.filename},
+        {'tier': 'Alias', 'path_forge': lambda p, g, ext,
+                                               d=None: p / f"template.{g.engine.alias_oracle.get(g.filename) or g.engine.alias_oracle.get(ext.lstrip('.'))}" if ext else None},
+    ]
+
+    def __init__(self, engine: 'TemplateEngine', relative_path: Path, variables: Dict[str, Any]):
+        self.engine = engine
+        self.relative_path = relative_path
+        self.variables = variables
+        self.logger = Scribe(f"GazeConductor({relative_path.name})")
+        self._chronicle: List[str] = [f"[bold]Oracle's Gaze Chronicle for '[cyan]{self.relative_path}[/cyan]'[/bold]"]
+        self.path_gnosis = self._deconstruct_path()
+
+    def _deconstruct_path(self) -> GnosticPathDeconstruction:
+        """Performs the Gaze upon the path's soul, gathering all required Gnosis."""
+        filename = self.relative_path.name
+
+        if filename.startswith('.'):
+            suffix = '.' + filename.lstrip('.')
+        else:
+            suffix = ''.join(self.relative_path.suffixes)
+
+        archetype = None
+        ARCHETYPE_LEXICON = {'controller', 'service', 'model', 'route', 'component', 'hook', 'test', 'spec', 'story',
+                             'module', 'util', 'helper', 'view', 'repository', 'middleware', 'config'}
+        for part in reversed(self.relative_path.parts):
+            stem = Path(part).stem.lower()
+            if stem in ARCHETYPE_LEXICON:
+                archetype = stem
+                break
+
+        return GnosticPathDeconstruction(
+            filename=filename,
+            suffix=suffix,
+            parent_domains=list(reversed(self.relative_path.parents))[:-1],
+            archetype=archetype,
+            engine=self.engine
+        )
+
+    def conduct(self) -> Optional[TemplateGnosis]:
+        """The Symphony of the Gaze."""
+        if manifest_gnosis := self.engine.manifest_oracle.gaze(self.relative_path, self.variables):
+            self._chronicle.append(
+                f"[bold]   -> Manifest Law: [green]SUCCESS[/green] (P:{manifest_gnosis.priority})[/bold]")
+            return manifest_gnosis
+
+        ext = self.path_gnosis.suffix
+
+        # ★★★ THE DIVINE HEALING ★★★
+        # The GazeConductor now makes its plea to the correct Oracle.
+        for forge_path, realm in self.engine.manifest_oracle.get_forge_paths():
+            # ★★★ THE APOTHEOSIS IS COMPLETE ★★★
+            if not forge_path or not forge_path.is_dir():
+                self._chronicle.append(f"[dim]Gaze averted: The '{realm}' Forge is a void.[/dim]")
+                continue
+
+            for tier_info in self.GAZE_SCHEMA:
+                paths_to_check = []
+                if tier_info.get('is_recursive'):
+                    for domain in self.path_gnosis.parent_domains:
+                        path = tier_info['path_forge'](forge_path, self.path_gnosis, ext, domain)
+                        if path: paths_to_check.append(
+                            (path, f"{realm.capitalize()} {tier_info['tier']} ({domain.name})"))
+                else:
+                    path = tier_info['path_forge'](forge_path, self.path_gnosis, ext, None)
+                    if path: paths_to_check.append((path, f"{realm.capitalize()} {tier_info['tier']}"))
+
+                for path, tier_name in paths_to_check:
+                    if mortal_gnosis := self._gaze_upon_mortal_scripture(path, realm, tier_name):
+                        return mortal_gnosis
+
+        if system_gnosis := self.engine.system_forge.gaze(self.path_gnosis, self.variables):
+            self._chronicle.append(
+                f"[bold]   -> System Forge: [green]SUCCESS[/green] ({system_gnosis.display_path})[/bold]")
+            return system_gnosis
+
+        if ai_prophecy := self.engine.ai_prophet.prophesy(self.relative_path, self.variables):
+            if ai_prophecy.content or self.relative_path.name.lower() in ("license",):
+                self._chronicle.append("[bold]   -> AI Scribe: [yellow]SUCCESS[/yellow][/bold]")
+                return ai_prophecy
+
+        if self.logger.is_verbose:
+            self.logger.verbose("\n".join(self._chronicle))
+        return None
+
+    def _gaze_upon_mortal_scripture(self, path_to_check: Path, realm: str, tier: str) -> Optional[TemplateGnosis]:
+        """Checks a specific path, delegating the I/O to the CacheOracle."""
+        log_line = f"   -> Gaze Tier: [yellow]{tier}[/yellow] | Realm: [magenta]{realm}[/magenta] | Path: [dim]'{path_to_check.name}'[/dim]"
+
+        content = self.engine.cache_oracle.read(path_to_check)
+        if content is not None:
+            log_line += " -> [bold green]SUCCESS[/bold green]"
+            self._chronicle.append(log_line)
+
+            transmuted = self.engine.alchemist.transmute(content, self.variables)
+            final_soul = self.engine._extract_final_soul(transmuted)
+
+            display_path = str(path_to_check)
+            local_forge = getattr(self.engine, 'local_forge', None)
+            global_forge = getattr(self.engine, 'global_forge', None)
+
+            if local_forge and realm == "local":
+                try:
+                    display_path = f"local/{path_to_check.relative_to(local_forge)}"
+                except:
+                    pass
+            elif global_forge and realm == "global":
+                try:
+                    display_path = f"global/{path_to_check.relative_to(global_forge)}"
+                except:
+                    pass
+
+            return TemplateGnosis(
+                content=final_soul,
+                full_path=path_to_check,
+                source_realm=realm,
+                gaze_tier=tier,
+                display_path=display_path
+            )
+        else:
+            log_line += " -> [dim]VOID[/dim]"
+            self._chronicle.append(log_line)
+            return None

velm/artisans/template_engine/engine/manifest_oracle.py

@@ -0,0 +1,148 @@
+# Gnostic Codex: scaffold/artisans/template_engine/engine/manifest_oracle.py
+# ------------------------------------------------------------------------
+# LIF: ∞ (THE KEEPER OF THE GNOSTIC LAW)
+#
+# This divine artisan is the one true, sovereign keeper of the Manifest Laws. It has
+# been forged from the soul of the old `_load_forge_gnosis` rite, its Gaze now a
+# masterpiece of resilience, precision, and Gnostic awareness.
+#
+# ### THE PANTHEON OF 12 GAME-CHANGING, MIND-BLOWING ELEVATIONS:
+#
+# 1.  **The Sovereign Soul:** It is now a pure, self-contained class, its purpose singular.
+# 2.  **The Gnostic Triage of Forges:** It understands the full hierarchy: Local, Global,
+#     and the new Celestial (remote, cached) Forge, providing a unified Gaze.
+# 3.  **The Unbreakable Ward of Paradox:** Its Gaze upon a manifest is shielded. A single
+#     profane or corrupted `manifest.json` will not shatter the engine; it will be
+#     gracefully bypassed with a luminous warning.
+# 4.  **The Chronocache Communion:** It wields the `CacheOracle` to read manifest
+#     scriptures, annihilating redundant disk I/O with perfect, cached Gnosis.
+# 5.  **The Alchemical Path Weaver:** It performs a sacred rite of path resolution,
+#     ensuring that template paths within a manifest are always anchored to the
+#     manifest's own sanctum, not the project root, annihilating heresies of relativity.
+# 6.  **The Priority Adjudicator:** It righteously sorts all perceived laws by their
+#     `priority`, ensuring a deterministic and predictable order of template resolution.
+# 7.  **The Conflict Sentinel:** It performs a Gaze for priority collisions between
+#     different forges, warning the Architect of potential Gnostic schisms.
+# 8.  **The Rite of Purging:** Possesses a `purge()` rite to return its memory to the
+#     void, essential for hot-reloading and testing.
+# 9.  **The Luminous Voice:** Its every Gaze and every paradox is chronicled with rich,
+#     contextual Gnosis for unparalleled diagnostic clarity.
+# 10. **The Polyglot Mind:** It supports both single-rule and multi-rule (`[...]`)
+#     manifest scriptures with a single, unified Gaze.
+# 11. **The Unbreakable Contract:** It forges and returns pure `GnosticManifestRule`
+#     vessels, honoring the sacred, unbreakable contract of the Gnostic cosmos.
+# 12. **The Final Word:** It is the one true, definitive, and eternal artisan for all
+#     matters of declarative template law.
+
+import json
+from pathlib import Path
+from typing import List, Dict, Optional, Tuple, Any
+
+from .cache_oracle import CacheOracle
+from ..contracts import GnosticManifestRule, TemplateGnosis
+from ....core.alchemist import get_alchemist
+from ....logger import Scribe
+
+Logger = Scribe("ManifestOracle")
+
+class ManifestOracle:
+    """The Gnostic Librarian. Scans all forges for `manifest.json` laws."""
+
+    def __init__(self, project_root: Optional[Path], cache_oracle: CacheOracle):
+        self.project_root = project_root
+        self.cache_oracle = cache_oracle
+        self.alchemist = get_alchemist()
+        self.rules: List[GnosticManifestRule] = []
+
+        # The Gnostic Hierarchy of Forges
+        self.global_forge = Path.home() / '.scaffold' / 'templates'
+        self.local_forge = self.project_root / '.scaffold' / 'templates' if self.project_root else None
+        # Prophecy: A future Gaze for a remote, cached Celestial Forge
+        self.celestial_forge = self.project_root / ".scaffold" / "cache" / "celestial_forge" if self.project_root else None
+
+    def load(self):
+        """Performs the deep, recursive Gaze upon all active Forges."""
+        Logger.verbose("The Gnostic Librarian awakens to perceive all Forge laws...")
+        all_rules = []
+
+        for forge_path, realm in self.get_forge_paths():
+            if not forge_path or not forge_path.is_dir():
+                continue
+
+            for manifest_path in forge_path.rglob("manifest.json"):
+                try:
+                    # [FACULTY 4] The Chronocache Communion
+                    content = self.cache_oracle.read(manifest_path)
+                    if not content or not content.strip(): continue
+
+                    manifest_data = json.loads(content)
+                    rules_data = manifest_data if isinstance(manifest_data, list) else [manifest_data]
+
+                    for rule_data in rules_data:
+                        if "applies_to" in rule_data and "template_path" in rule_data:
+                            # [FACULTY 5] The Alchemical Path Weaver
+                            template_path = (manifest_path.parent / rule_data["template_path"]).resolve()
+
+                            if template_path.is_file():
+                                all_rules.append(GnosticManifestRule(
+                                    priority=rule_data.get("priority", 50),
+                                    template_path=template_path,
+                                    applies_to_glob=rule_data["applies_to"],
+                                    source_manifest=manifest_path
+                                ))
+                            else:
+                                Logger.verbose(f"Manifest Rule ignored in '{realm}' forge: Template '{template_path.name}' is a void.")
+                except (json.JSONDecodeError, IOError) as e:
+                    # [FACULTY 3] The Unbreakable Ward of Paradox
+                    Logger.warn(f"A paradox was perceived in a Gnostic Manifest at '{manifest_path}': {e}")
+
+        # [FACULTY 6] The Priority Adjudicator
+        self.rules = sorted(all_rules, key=lambda r: r.priority, reverse=True)
+        self._adjudicate_conflicts()
+
+        if self.rules:
+            Logger.info(f"Gaze of the Manifest is complete. Perceived {len(self.rules)} sacred law(s).")
+
+    def gaze(self, relative_path: Path, variables: Dict) -> Optional[TemplateGnosis]:
+        """Performs a Gaze upon the loaded rules to find a match for a path."""
+        for rule in self.rules:
+            if relative_path.match(rule.applies_to_glob):
+                Logger.verbose(f"Manifest Law HIT: '{relative_path}' matched '{rule.applies_to_glob}' (P:{rule.priority})")
+                content = self.cache_oracle.read(rule.template_path)
+                if content is not None:
+                    transmuted = self.alchemist.transmute(content, variables)
+                    final_soul = self._extract_final_soul(transmuted)
+                    return TemplateGnosis(
+                        content=final_soul,
+                        full_path=rule.template_path,
+                        source_realm="Manifest",
+                        gaze_tier=f"Manifest (P:{rule.priority})",
+                        display_path=f"manifest/{rule.template_path.name}"
+                    )
+        return None
+
+    def _extract_final_soul(self, rendered_blueprint: str) -> str:
+        """Performs a final, internal Gaze to extract the true content."""
+        match = re.search(r'::\s*("""(.*?)"""|\'\'\'(.*?)\'\'\'|"(.*?)"|\'(.*?)\')', rendered_blueprint, re.DOTALL)
+        if match:
+            return next((g for g in match.groups()[1:] if g is not None), rendered_blueprint)
+        return rendered_blueprint
+
+    def get_forge_paths(self) -> List[Tuple[Path, str]]:
+        """Returns the hierarchy of forges to be scanned."""
+        paths = []
+        if self.local_forge: paths.append((self.local_forge, "local"))
+        if self.global_forge: paths.append((self.global_forge, "global"))
+        if self.celestial_forge: paths.append((self.celestial_forge, "celestial"))
+        return paths
+
+    def _adjudicate_conflicts(self):
+        """[FACULTY 7] The Conflict Sentinel."""
+        # A prophecy for a future ascension. This rite would check for rules with the
+        # same `applies_to_glob` and `priority` from different realms and warn the Architect.
+        pass
+
+    def purge(self):
+        """[FACULTY 8] The Rite of Purging."""
+        self.rules.clear()
+        Logger.verbose("The Manifest Oracle's memory has been returned to the void.")