gitgalaxy 0.1.0__py3-none-any.whl

gitgalaxy/aperture.py

@@ -0,0 +1,315 @@
+import os
+import logging
+import fnmatch
+from pathlib import Path
+from typing import Dict, Any, Set, Optional, TypedDict, Union, List, Tuple
+
+# ==============================================================================
+# GitGalaxy Phase 0.1: Ingestion & Filtering (The Solar Shield)
+# Strategy: v6.2.0 (Bayesian Optics, Intent Overrides & Stateful Caching)
+# Architecture: Lead Shield -> Path Gate -> Intent Gate -> Content Gate
+# ==============================================================================
+
+# --- CUSTOM EXCEPTION HIERARCHY (The Lead Shield) ---
+
+class ApertureError(Exception):
+    """Base class for all errors generated by the Solar Shield filtering process."""
+    pass
+
+class InaccessibleArtifactError(ApertureError):
+    """Raised when an artifact cannot be accessed due to OS permissions or path corruption."""
+    pass
+
+class SaturationError(ApertureError):
+    """Raised when a signal is too dense or minified to be safely refracted by the detector."""
+    pass
+
+class FilterResult(TypedDict):
+    """Structured telemetry returned by the Solar Shield for the Pipeline Orchestrator."""
+    is_in_scope: bool
+    band: str
+    reason: Optional[str]
+    path: str
+    size_bytes: int
+    total_loc: int
+
+
+class ApertureFilter:
+    """
+    Primary solar shield for the telescope. Performs perimeter gating to ensure 
+    only maintainable source code matter reaches the detector. Integrates with 
+    GuideStar's Bayesian 'Intent Locks' to dynamically adjust suppression 
+    thresholds for known, high-priority artifacts.
+    """
+
+    def __init__(
+        self, 
+        root_dir: Union[str, Path], 
+        language_definitions: Dict[str, Any], 
+        aperture_config: Dict[str, Any],
+        parent_logger: Optional[logging.Logger] = None
+    ):
+        # --- TELEMETRY SYNC ---
+        if parent_logger:
+            self.logger = parent_logger.getChild("filter")
+            self.logger.setLevel(parent_logger.level)
+        else:
+            self.logger = logging.getLogger("filter")
+            self.logger.setLevel(logging.INFO)
+        self.root = Path(root_dir).resolve()
+        self.registry = language_definitions
+        
+        # 1. Safely bind the config passed down from the Orchestrator
+        self.config = aperture_config or {}
+        
+        # 2. Extract specific variables from the config payload
+        self.bands = self.config.get("BANDS", {
+            "RADIO": "radio_noise", "MICROWAVE": "binary_debris", 
+            "DARK_MATTER": "unknown_ext", "INFRARED": "saturated", 
+            "VISIBLE": "source_code"
+        })
+        self.black_holes = set(self.config.get("EXCLUDED_DIRECTORIES", set()))
+        self.black_hole_exts = set(self.config.get("BLACKLISTED_EXTENSIONS", set())) 
+        
+        # --- STATE CACHE --- 
+        self._intent_cache: Set[str] = set()
+        
+        self.logger.debug(f"Initializing Solar Shield for sector: '{self.root.name}'...")
+
+        # Optimized lookup sets from Language Definitions
+        self.whitelisted_extensions: Set[str] = set()
+        self.ecosystem_anchors: Set[str] = set()
+        
+        for lang_id, data in self.registry.items():
+            self.whitelisted_extensions.update(data.get('extensions', []))
+            self.ecosystem_anchors.update(data.get('exact_matches', []))
+
+        self.ignore_patterns = self._load_gitignore_patterns()
+        
+        self.logger.info(
+            f"Dispatching Survey Probe to Sector '{self.root.name}' | "
+            f"Tracking {len(self.whitelisted_extensions)} spectral bands."
+        )
+
+    def evaluate_path_integrity(self, file_path: Union[str, Path], has_intent: bool = False) -> Tuple[bool, int, str]:
+        """
+        [PHASE 0 ENTRY POINT]
+        Fast path-only check to build the CensusArray (Radar Walk).
+        Now safely fetches file size to prevent the 0-Byte Dark Matter telemetry bug.
+        
+        Args:
+            file_path: The artifact's path.
+            has_intent: True if the GuideStar mapped this file in a manifest or priority list.
+            
+        Returns:
+            Tuple: (is_valid: bool, size_bytes: int, reason: str)
+        """
+        path_obj = Path(file_path)
+        normalized_path = path_obj.as_posix()
+        _, ext = os.path.splitext(path_obj.name)
+        
+        try:
+            relative_path = path_obj.relative_to(self.root).as_posix()
+        except ValueError:
+            relative_path = normalized_path
+
+        # Safely fetch size before making drop decisions to ensure accurate Dark Matter telemetry
+        try:
+            size_bytes = path_obj.stat().st_size if path_obj.exists() else 0
+        except OSError:
+            size_bytes = 0
+
+        # 0. TIER 0.5: THE ABSOLUTE EXTENSION SHIELD (Impervious to Intent)
+        # Drops SVGs, 3D Models, PDFs, and PGP keys before disk I/O ever happens.
+        if ext.lower() in self.black_hole_exts:
+            reason = f"Blocked (Explicitly Blacklisted Media/Binary Extension: '{ext}')"
+            self.logger.debug(f"{reason}: {relative_path}")
+            return False, size_bytes, reason
+
+        # Resolve intent status against cache
+        active_intent = has_intent or (normalized_path in self._intent_cache)
+        if active_intent:
+            self._intent_cache.add(normalized_path)
+
+        # 1. TIER 1: THE SOLAR SHIELD (Radio Noise)
+        if not self._check_solar_shield(relative_path, has_intent=active_intent):
+            reason = "Blocked (Path Excluded by System Rules, Hidden Directory, or .gitignore)"
+            self.logger.debug(f"{reason}: {relative_path}")
+            return False, size_bytes, reason
+
+        # --- INTENT BYPASS ---
+        # If the file has a GuideStar lock, it bypasses linguistic whitelisting entirely.
+        if active_intent:
+            reason = "Passed (GuideStar Intent Lock Bypassed Tier 2)"
+            self.logger.debug(f"{reason}: {relative_path}")
+            return True, size_bytes, reason
+
+        # 2. TIER 2: THE VISIBLE SPECTRUM (Linguistic Whitelisting)
+        # Rule 2.1: Deep Space Remnants (Spec 2.3.3.B)
+        # We allow extensionless files through without intent to be evaluated by the Shebang Scanner
+        if not ext:
+            reason = "Passed (Extensionless -> Shebang scan required)"
+            self.logger.debug(f"{reason}: {relative_path}")
+            return True, size_bytes, reason
+            
+        # Rule 2.2: Known Ecosystem Anchor or Whitelisted Extension
+        if path_obj.name in self.ecosystem_anchors or ext.lower() in self.whitelisted_extensions:
+            reason = "Passed (Ecosystem Anchor or Whitelisted Ext)"
+            return True, size_bytes, reason
+
+        reason = f"Blocked (Unsupported or Unrecognized Extension: '{ext}')"
+        self.logger.debug(f"{reason}: {relative_path}")
+        return False, size_bytes, reason
+
+    def is_in_scope(self, file_path: Union[str, Path], content: Optional[str] = None, has_intent: bool = False) -> FilterResult:
+        """Runs the 5-tier perimeter gate to validate maintainable code matter."""
+        path_obj = Path(file_path)
+        normalized_path = path_obj.as_posix() 
+        
+        try:
+            relative_path = path_obj.relative_to(self.root).as_posix()
+        except ValueError:
+            relative_path = normalized_path
+
+        # Pull from state to guarantee consistency between Phase 0 and Phase 1 calls
+        active_intent = has_intent or (normalized_path in self._intent_cache)
+
+        result: FilterResult = {
+            "is_in_scope": False,
+            "band": self.bands.get("VISIBLE", "source_code"),
+            "reason": None,
+            "path": normalized_path,
+            "size_bytes": 0,
+            "total_loc": 0
+        }
+
+        try:
+            # --- TIER 0: THE LEAD SHIELD (Resource Guarding) ---
+            # NOTE: Intent cannot override file size or existence checks. Physics are absolute.
+            if not path_obj.exists():
+                raise InaccessibleArtifactError("Artifact missing or path invalid")
+            
+            stats = path_obj.stat()
+            result["size_bytes"] = stats.st_size
+            
+            max_mb = self.config.get("MAX_FILE_SIZE_MB", 10)
+            if stats.st_size > (max_mb * 1024 * 1024):
+                self.logger.warning(f"Resource Guard: Rejected massive file '{relative_path}' ({stats.st_size / (1024 * 1024):.1f} MB)")
+                result["band"] = self.bands.get("INFRARED", "saturated")
+                result["reason"] = f"Blocked (File Size Exceeds Configured Limit: > {max_mb}MB)"
+                return result
+
+            # --- TIER 1 & 2: PATH VALIDATION ---
+            is_valid, size_bytes, reason = self.evaluate_path_integrity(path_obj, has_intent=active_intent)
+            if not is_valid:
+                result["band"] = self.bands.get("RADIO", "radio_noise")
+                result["reason"] = reason
+                result["size_bytes"] = size_bytes
+                return result
+
+            # --- TIER 3 & 4: ARTIFACT INTEGRITY (Content Gate) ---
+            if content is None:
+                self.logger.warning(f"Protocol Violation: Missing content buffer for '{relative_path}'")
+                result["reason"] = "Protocol Violation: Missing content buffer"
+                return result
+
+            integrity = self._check_artifact_integrity(content, relative_path)
+            result["total_loc"] = integrity["loc"]
+            
+            if not integrity["valid"]:
+                result["band"] = integrity["band"]
+                result["reason"] = integrity["reason"]
+                return result
+
+            # --- SUCCESS ---
+            result["is_in_scope"] = True
+            self.logger.debug(f"Aperture Lock: '{relative_path}' safely in scope (LOC: {result['total_loc']}).")
+            return result
+
+        except (InaccessibleArtifactError, PermissionError) as e:
+            self.logger.warning(f"Inaccessible Artifact: '{relative_path}' | {str(e)}")
+            result["band"] = self.bands.get("RADIO", "radio_noise")
+            result["reason"] = f"I/O Exception: {str(e)}"
+            return result
+        except Exception as e:
+            self.logger.error(f"Critical Solar Shield Failure on '{relative_path}': {str(e)}", exc_info=True)
+            result["reason"] = f"Internal Exception: {str(e)}"
+            return result
+
+    def _check_artifact_integrity(self, content: str, rel_path: str) -> Dict[str, Any]:
+        """Inspects the Photon Buffer for corruption or saturation."""
+        report = {"valid": True, "band": self.bands.get("VISIBLE", "source_code"), "reason": None, "loc": 0}
+        
+        # --- TIER 3: THE LEAD SHIELD (Binary Detection) ---
+        # FIX: Removed the [:1024] slice. We must check the entire buffer 
+        # so binary files don't sneak into Visible Stars.
+        if '\x00' in content:
+            self.logger.debug(f"Integrity check failed (Opaque Binary / Null Bytes): {rel_path}")
+            report.update({
+                "valid": False,
+                "band": self.bands.get("MICROWAVE", "binary_debris"),
+                "reason": "Blocked (Binary Format: Null bytes detected during read)"
+            })
+            return report
+
+        # --- TIER 4: INFRARED GATE (Minification & Saturation) ---
+        max_line = self.config.get("MAX_LINE_LENGTH", 500)
+        scan_limit = self.config.get("MINIFICATION_SCAN_LIMIT", 50)
+        
+        lines = content.splitlines()
+        report["loc"] = len(lines)
+
+        for i, line in enumerate(lines):
+            if i < scan_limit:
+                if len(line) > max_line:
+                    self.logger.debug(f"Integrity check failed: '{rel_path}' saturated > {max_line} chars on line {i+1}")
+                    report.update({
+                        "valid": False,
+                        "band": self.bands.get("INFRARED", "saturated"),
+                        "reason": f"Blocked (Minified or Dense Data: Line {i+1} exceeds {max_line} characters)"
+                    })
+                    return report
+            else:
+                break
+        
+        return report
+
+    def _load_gitignore_patterns(self) -> List[str]:
+        """Reads local .gitignore files to identify Radio Noise."""
+        patterns = []
+        ignore_file = self.root / ".gitignore"
+        if ignore_file.exists():
+            try:
+                with ignore_file.open('r', encoding='utf-8') as f:
+                    for line in f:
+                        line = line.strip()
+                        if line and not line.startswith('#'):
+                            patterns.append(line)
+            except (IOError, OSError) as e:
+                self.logger.warning(f"Failed to load .gitignore rules: {e}")
+        return patterns
+
+    def _check_solar_shield(self, rel_path: str, has_intent: bool = False) -> bool:
+        """Determines if the path sits in a blocked or ignored sector."""
+        parts = rel_path.split('/')
+        
+        for part in parts:
+            if part in self.black_holes:
+                return False
+            
+            # Hidden Path Suppression (e.g., .github/, .vscode/)
+            if part.startswith('.') and part not in self.ecosystem_anchors:
+                # If GuideStar explicitly mapped a dotfile (e.g., .hooks/pre-commit), lift the blockade.
+                if has_intent:
+                    self.logger.debug(f"Solar Shield VIP Pass: Bypassing hidden-path block for intent-locked artifact '{part}'")
+                    continue
+                self.logger.debug(f"Blocked by Hidden Path Component '{part}': {rel_path}")
+                return False
+        
+        for pattern in self.ignore_patterns:
+            if pattern.endswith('/') and any(fnmatch.fnmatch(p + '/', pattern) for p in parts):
+                return False
+            if fnmatch.fnmatch(rel_path, pattern) or fnmatch.fnmatch(parts[-1], pattern):
+                return False
+        
+        return True

gitgalaxy/audit_recorder.py

@@ -0,0 +1,277 @@
+import json
+import argparse
+import os
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from . import gitgalaxy_standards_v011 as config
+
+# ==============================================================================
+# GitGalaxy Phase 8 & 9: Astrograph Auditor (The Forensic Record)
+# Strategy v6.2.0 Protocol: Raw-Matter Preservation & Columnar Decoding
+# Stage 2.5: Total Feature Parity (Descriptive Descriptors + Performance)
+# ==============================================================================
+
+class AuditRecorder:
+    """
+    The GitGalaxy Audit Recorder.
+    
+    PURPOSE: Generates a verbose, human-readable forensic log from live RAM data.
+    Designed for compliance, debugging, and deep-dive analysis.
+    """
+
+    def __init__(self, parent_logger=None):
+        import logging
+        self.logger = parent_logger.getChild("audit_recorder") if parent_logger else logging.getLogger("audit_recorder")
+
+        # --- DYNAMIC SCHEMA FETCH ---
+        schemas = getattr(config, "RECORDING_SCHEMAS", {})
+        self.RISK_SCHEMA = schemas.get("RISK_SCHEMA", [])
+        # Note: The pipeline calls it SIGNAL_SCHEMA, but the Auditor references it as HIT_SCHEMA
+        self.HIT_SCHEMA = schemas.get("SIGNAL_SCHEMA", []) 
+
+        # Performance optimization: Pre-cache all labels to avoid regex on the hot path
+        self._label_cache = {}
+        self._friendly_map = schemas.get("FRIENDLY_MAP", {})
+
+    def format_label(self, key: str) -> str:
+        """Translates raw keys into descriptive labels using a fast-lookup cache."""
+        if key in self._label_cache:
+            return self._label_cache[key]
+            
+        clean_key = re.sub(r'_x\d+$', '', key)
+        label = self._friendly_map.get(clean_key)
+        
+        if not label:
+            label = " ".join(word.capitalize() for word in clean_key.split('_'))
+            
+        self._label_cache[key] = label
+        return label
+
+    def descale(self, key: str, value: Any, default_scalar: float = 1.0) -> Any:
+        """Dynamically scales integers back to floats using a fixed-string check."""
+        if not isinstance(value, (int, float)) or isinstance(value, bool):
+            return value
+            
+        if key.endswith("_x1000"):
+            return round(value / 1000.0, 3)
+        if key.endswith("_x10"):
+            return round(value / 10.0, 3)
+            
+        if default_scalar != 1.0:
+            return round(value / default_scalar, 3)
+        return value
+
+    def generate_report(self, stars, singularity, summary, forensic_report, session_meta, output_path):
+        """
+        Subphase 2.3: Transforms raw pipeline data into a verbose forensic manifest.
+        Optimized to handle projects with 10,000+ files efficiently.
+        """
+        # 1. Forensic Traceability Anchor
+        git_audit = session_meta.get("git_audit", {})
+        forensic_trail = {
+            "Analysis Context": {
+                "Engine Identity": session_meta.get("engine", "GitGalaxy Scope v6.2.0"),
+                "Target Root Name": session_meta.get("target", "Unknown"),
+                "Absolute Project Path": session_meta.get("target_directory", "Unknown"),
+                "Analysis ISO Timestamp": session_meta.get("timestamp"),
+                "Total Scan Duration": f"{session_meta.get('duration_seconds', 0.0)} seconds"
+            },
+            "Source Control Footprint (Immutable Anchor)": {
+                "Active Branch": git_audit.get("branch", "N/A"),
+                "Commit Hash (SHA-1)": git_audit.get("commit_hash", "N/A"),
+                "Remote Origin URL": git_audit.get("remote_url", "Local/Disconnected"),
+                "Last Code Integration Date": git_audit.get("latest_commit_date", "Unknown")
+            }
+        }
+
+        # --- DYNAMIC TRANSLATION FETCH ---
+        schemas = getattr(config, "RECORDING_SCHEMAS", {})
+        exposure_labels = schemas.get("EXPOSURE_LABELS", {})
+
+        # Pre-calculate labels for vectors to avoid repeating work in the loop
+        risk_labels = [exposure_labels.get(k, self.format_label(k)) for k in self.RISK_SCHEMA]
+        hit_labels = [self.format_label(k) for k in self.HIT_SCHEMA]
+
+        # --- NEW CONSTELLATION SORTING & HIERARCHY ---
+        pretty_constellations = {}
+        constellations_meta = summary.get("constellations", {})
+        
+        # Sort folders by mass descending
+        sorted_constellations = sorted(
+            constellations_meta.items(), 
+            key=lambda x: x[1].get("total_mass", 0.0), 
+            reverse=True
+        )
+
+        # Initialize the ordered dictionary with constellation-level metrics
+        for c_name, c_data in sorted_constellations:
+            pretty_constellations[c_name] = {
+                "Constellation Mass": c_data.get("total_mass", 0.0),
+                "File Count": c_data.get("file_count", 0),
+                "Average Risk Exposures": {
+                    exposure_labels.get(k, self.format_label(k)): f"{v}%" 
+                    for k, v in c_data.get("avg_exposures", {}).items()
+                },
+                "Stars / Files": {}
+            }
+
+        # 2. Row Reconstruction (Visible Stars) mapped into Constellations
+        for star in stars:
+            path = star.get("path", "Unknown")
+            telemetry = star.get("telemetry", {})
+            lang_raw = str(star.get("lang_id", "Unknown")).lower()
+            c_name = star.get("constellation", "__monolith__")
+            
+            # --- THE ULTIMATE UPSTREAM BYPASS FIX ---
+            doc_languages = {"markdown", "plaintext", "rst", "text", "md"}
+            if lang_raw in doc_languages and len(star.get("risk_vector", [])) < len(self.RISK_SCHEMA):
+                # Inject 13-point synthetic Risk Blanket
+                star["risk_vector"] = [0.0, 100.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 100.0, 100.0, 0.0, 100.0, 0.0]
+                telemetry["control_flow_ratio"] = 0.0
+                if not star.get("file_impact"):
+                    star["file_impact"] = round(max(star.get("total_loc", 1) / 50.0, 1.0), 2)
+            
+            # --- SYSTEM LEVEL FIX: Dynamic Identity Block ---
+            identity_block = {
+                "Filename": star.get("name", Path(path).name),
+                "Path": path,
+                "Language": str(star.get("lang_id", "Unknown")).title(),
+                "Architect": telemetry.get("ownership", "Unknown Architect")
+            }
+            
+            domain_data = telemetry.get("domain_context", {})
+            for custom_key, custom_val in domain_data.items():
+                if custom_key != "ownership":
+                    display_key = custom_key.replace('_', ' ').title()
+                    if display_key == "Purpose":
+                        display_key = "Museum Entry"
+                    identity_block[display_key] = custom_val
+
+            identity_block["Lock Tier"] = star.get("lock_tier", telemetry.get("identity_lock_tier", 4))
+            identity_block["Identity Proof"] = telemetry.get("identity_source_proof", star.get("source_proof", "Discovery"))
+            
+            # --- THE FACTION INTERCEPTOR ---
+            exposures_dict = {}
+            for label, v in zip(risk_labels, star.get("risk_vector") or [0.0] * len(risk_labels)):
+                if label == "Civil War Exposure":
+                    if v == 0.0: 
+                        exposures_dict[label] = "Team Tabs"
+                    elif v == 100.0: 
+                        exposures_dict[label] = "Team Spaces"
+                    elif v == 50.0: 
+                        exposures_dict[label] = "Neutral / Deadlocked"
+                    else: 
+                        exposures_dict[label] = f"Mixed ({100-v:.1f}% Tabs / {v:.1f}% Spaces)"
+                else:
+                    exposures_dict[label] = f"{round(v, 2)}%"
+
+            # Assemble the star profile
+            star_profile = {
+                "1. Identity": identity_block,
+                "2. Spatial Coordinates": {
+                    "X": star.get("pos_x", 0.0), 
+                    "Y": star.get("pos_y", 0.0), 
+                    "Z": star.get("pos_z", 0.0)
+                },
+                "3. Galactic Profile": {
+                    "Total LOC": star.get("total_loc", 0),
+                    "coding LOC": star.get("coding_loc", 0),
+                    "Documentation LOC": star.get("doc_loc", 0),
+                    "Structural Mass": round(star.get("file_impact", 0.0), 3),
+                    "Control Flow Ratio": f"{round(telemetry.get('control_flow_ratio', 0.0) * 100, 1)}%",
+                    "Popularity Rank": telemetry.get("popularity", 0)
+                },
+                "4. Risk Exposures": exposures_dict,
+                "5. Function Analysis (Satellites)": [
+                    {
+                        "Function Name": sat.get("name", "Unknown"),
+                        "Structural Impact": sat.get("impact", sat.get("magnitude", 0.0)),
+                        "Lines of Code (LOC)": sat.get("loc", 0),
+                        "Control Flow Branches": sat.get("branch", sat.get("branch_count", 0)),
+                        "Input Parameters": sat.get("args", sat.get("args_count", 0)),
+                        "Control Flow Ratio": f"{round(sat.get('control_flow_ratio', sat.get('cf_ratio', 0.0)) * 100, 1)}%",
+                        "Start Line": sat.get("start_line", 0),
+                        "End Line": sat.get("end_line", 0)
+                    }
+                    for sat in star.get("satellites", []) if isinstance(sat, dict)
+                ],
+                "6. Structural DNA (Raw Hits)": {
+                    label: v for label, v in zip(hit_labels, star.get("hit_vector") or [0] * len(hit_labels))
+                },
+                "7. Extracted Dependencies": sorted(list(star.get("raw_imports", [])))
+            }
+            
+            # Map the star into its parent constellation
+            if c_name not in pretty_constellations:
+                pretty_constellations[c_name] = {"Constellation Mass": 0.0, "Stars / Files": {}}
+            pretty_constellations[c_name]["Stars / Files"][path] = star_profile
+
+        # 3. Format Dark Matter (Excluded Artifacts)
+        pretty_singularity = []
+        target_dir = Path(session_meta.get("target_directory", ""))
+
+        # 3.1 Format standard excluded items for the JSON output
+        for dark in singularity:
+            rel_path = dark.get("path", "Unknown")
+            abs_path = target_dir / rel_path
+            
+            # Physically weighs the file on disk if the pipeline dropped the byte count
+            try:
+                actual_size = os.path.getsize(abs_path) if abs_path.exists() else dark.get('size_bytes', 0)
+            except Exception:
+                actual_size = dark.get('size_bytes', 0)
+
+            pretty_singularity.append({
+                "Path": rel_path,
+                "Forensic Category": "Dark Matter (Excluded Artifact)",
+                "Diagnostic Reason": dark.get("reason", "Engine Shielding (Format Excluded)"),
+                "Size": f"{actual_size} bytes",
+                "Identity Confidence": f"{round(dark.get('identity_confidence', 0.0) * 100, 1)}%",
+                "Discovery Proof": dark.get("identity_source_proof", "Radar Scan")
+            })
+
+        # 3.2 Append optically bypassed artifacts to the local output list
+        for anon_path in summary.get("singularity", {}).get("unparsable_artifacts", []):
+            pretty_singularity.append({
+                "Path": anon_path,
+                "Forensic Category": "Dark Matter (Optical Bypass)",
+                "Diagnostic Reason": "Engine Bypass (Dense Structure or Unrecognized Syntax)",
+                "Size": "Unknown (Prism Bypass)",
+                "Identity Confidence": "0.0% (Scan Yielded No Data)",
+                "Discovery Proof": "Logic Splicer Shielding"
+            })
+
+        # 4. Final Mission Archive Packaging
+        mission_audit = {
+            "Audit Protocol": "GitGalaxy v6.2.0-Audit",
+            "1. Forensic Trail (Traceability)": forensic_trail,
+            "2. Global Synthesis Summary": summary,
+            "3. High-Value Forensic Report": forensic_report,
+            "4. Dark Matter (Excluded Artifacts)": pretty_singularity,
+            "5. Visible Matter (Scanned Artifacts)": pretty_constellations
+        }
+
+        # --- ABSOLUTE ROUTING LOGIC ---
+        base_dir = Path("/srv/storage_16tb/projects/gitgalaxy/data")
+        base_dir.mkdir(parents=True, exist_ok=True)
+        safe_filename = Path(output_path).name
+        target_path = base_dir / safe_filename
+
+        try:
+            with open(target_path, 'w', encoding='utf-8') as f:
+                json.dump(mission_audit, f, indent=4, ensure_ascii=False)
+            self.logger.info(f"Audit Success: Forensic manifest sealed -> {target_path}")
+        except Exception as e:
+            self.logger.error(f"Audit Write Error: {e}")
+
+def decode_galaxy(input_path, output_path=None):
+    """Standalone decoding logic preserved for CLI compatibility."""
+    pass
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="GitGalaxy v6.2.0 Astrograph Auditor CLI")
+    parser.add_argument("input", help="Path to columnar galaxy.json")
+    parser.add_argument("--out", help="Optional output path")
+    args = parser.parse_args()