pgc-compiler 2.0.0__py3-none-any.whl

compiler/VERSION

@@ -0,0 +1 @@
+14

compiler/__init__.py

@@ -0,0 +1 @@
+"""compiler — Protocol Intermediate Representation compiler for PGS."""

compiler/atoms/__init__.py

@@ -0,0 +1,54 @@
+"""
+Atoms: Pure functions with no side effects.
+
+Design:
+- Single responsibility
+- Explicit inputs/outputs
+- No I/O, no state
+- Independently testable
+- Reusable across phases
+"""
+
+from compiler.atoms.error_codes import ErrorCode, ERROR_SUGGESTIONS
+from compiler.atoms.errors import CompilerError, Severity
+from compiler.atoms.fqdn import FQDN, parse_fqdn, build_fqdn, to_fqdn
+from compiler.atoms.invariants import require, require_not_none, require_exists
+from compiler.atoms.phase import PhaseResult, PhaseStatus, PhaseMetrics
+from compiler.atoms.pipeline import strip_transient_pipeline_fields
+from compiler.atoms.sorting import (
+    ensure_deterministic_output,
+    sort_artifacts_by_fqdn,
+    sort_by_fqdn,
+    sort_dict_keys,
+)
+from compiler.atoms.snapshot_gate import assert_snapshot_valid
+
+__all__ = [
+    # Error model
+    "CompilerError",
+    "ErrorCode",
+    "ERROR_SUGGESTIONS",
+    "Severity",
+    # FQDN identity
+    "FQDN",
+    "parse_fqdn",
+    "build_fqdn",
+    "to_fqdn",
+    # Phase results
+    "PhaseResult",
+    "PhaseStatus",
+    "PhaseMetrics",
+    # Invariant enforcement
+    "require",
+    "require_not_none",
+    "require_exists",
+    # Pipeline metadata
+    "strip_transient_pipeline_fields",
+    # Deterministic ordering
+    "ensure_deterministic_output",
+    "sort_artifacts_by_fqdn",
+    "sort_by_fqdn",
+    "sort_dict_keys",
+    # Snapshot admission control
+    "assert_snapshot_valid",
+]

compiler/atoms/error_codes.py

@@ -0,0 +1,160 @@
+"""
+Centralized error code registry.
+
+All error codes in one place to prevent:
+- String drift
+- Inconsistent reporting
+- Duplicate codes
+- Missing documentation
+
+Add new codes here, never inline in phase code.
+"""
+
+from enum import Enum
+
+
+class ErrorCode(Enum):
+    """
+    Error codes for the PGS compiler.
+
+    Organized by stage:
+    - E0xx: Discovery errors (S1)
+    - E1xx: Parse errors (S1)
+    - E2xx: Validation errors (S2–S4)
+    - E3xx: Materialization errors (S7)
+    - E4xx: Verification errors (S8)
+    - E7xx: ASSERT errors (S4)
+    - E8xx: Conformance errors (S7)
+    - E9xx: Internal/system errors
+    """
+
+    # ==================
+    # Discovery (E0xx)
+    # ==================
+    E001_NO_ARTIFACTS = "E001_NO_ARTIFACTS"
+    """No artifacts found in search path."""
+
+    E002_DUPLICATE_FQDN = "E002_DUPLICATE_FQDN"
+    """Duplicate FQDN detected (collision)."""
+
+    E003_INVALID_FILENAME = "E003_INVALID_FILENAME"
+    """Invalid filename pattern."""
+
+    E004_CROSS_REPO_REF = "E004_CROSS_REPO_REF"
+    """Cross-repo reference detected (source_path outside input_dir)."""
+
+    E005_DEPRECATED_ARTIFACT = "E005_DEPRECATED_ARTIFACT"
+    """Artifact marked status=deprecated; skipped during extraction."""
+
+    # ==================
+    # Parse (E1xx)
+    # ==================
+    E101_INVALID_YAML = "E101_INVALID_YAML"
+    """Invalid YAML frontmatter."""
+
+    E102_MISSING_FIELD = "E102_MISSING_FIELD"
+    """Missing required field."""
+
+    E103_TYPE_MISMATCH = "E103_TYPE_MISMATCH"
+    """Field type mismatch."""
+
+    E104_INVALID_FQDN = "E104_INVALID_FQDN"
+    """Invalid FQDN format."""
+
+    # ==================
+    # Validation (E2xx)
+    # ==================
+    E201_MISSING_REFERENCE = "E201_MISSING_REFERENCE"
+    """Reference to non-existent artifact (FQDN not found)."""
+
+    E202_CIRCULAR_DEPENDENCY = "E202_CIRCULAR_DEPENDENCY"
+    """Circular dependency detected (A→B→A)."""
+
+    E203_SCHEMA_INVALID = "E203_SCHEMA_INVALID"
+    """Schema validation failed (Pydantic error)."""
+
+    E204_INVALID_RB_BINDING = "E204_INVALID_RB_BINDING"
+    """RB references invalid CS artifact."""
+
+    E205_CT_VALIDATION_FAILED = "E205_CT_VALIDATION_FAILED"
+    """CT-IR validation failed."""
+
+    # ==================
+    # Materialization (E3xx)
+    # ==================
+    E301_WRITE_FAILED = "E301_WRITE_FAILED"
+    """Failed to write output file."""
+
+    E302_JSON_SERIALIZE_FAILED = "E302_JSON_SERIALIZE_FAILED"
+    """JSON serialization failed."""
+
+    # ==================
+    # Verification (E4xx)
+    # ==================
+    E401_MISSING_OUTPUT = "E401_MISSING_OUTPUT"
+    """Expected output file not found."""
+
+    E402_UNDECLARED_OUTPUT = "E402_UNDECLARED_OUTPUT"
+    """Output file not declared in expected outputs."""
+
+    E403_OUTPUT_MISMATCH = "E403_OUTPUT_MISMATCH"
+    """Output doesn't match expected schema."""
+
+    # ==================
+    # ASSERT Phase (E701-E750)
+    # ==================
+    E701_ASSERTION_FAILURE = "E701_ASSERTION_FAILURE"
+    """Assertion violations detected."""
+
+    E702_UNKNOWN_ASSERT = "E702_UNKNOWN_ASSERT"
+    """No executor for ASSERT artifact."""
+
+    E703_MALFORMED_ASSERT = "E703_MALFORMED_ASSERT"
+    """ASSERT artifact schema violation."""
+
+    # ==================
+    # Conformance (E8xx)
+    # ==================
+    E801_TEST_DATA_MISSING = "E801_TEST_DATA_MISSING"
+    """Test data missing for CT."""
+
+    E802_CONFORMANCE_FAILURE = "E802_CONFORMANCE_FAILURE"
+    """CT conformance test failed."""
+
+    E803_TEST_DATA_INVALID = "E803_TEST_DATA_INVALID"
+    """TEST_DATA does not match CT contract."""
+
+    # ==================
+    # Internal (E9xx)
+    # ==================
+    E901_INTERNAL_ERROR = "E901_INTERNAL_ERROR"
+    """Internal compiler error (bug)."""
+
+    E902_CONFIG_ERROR = "E902_CONFIG_ERROR"
+    """Configuration error."""
+
+
+# Error suggestions (actionable fixes)
+ERROR_SUGGESTIONS: dict[ErrorCode, str] = {
+    ErrorCode.E001_NO_ARTIFACTS: "Check input directory path and artifact_types config",
+    ErrorCode.E002_DUPLICATE_FQDN: "Rename artifact or change namespace to make FQDN unique",
+    ErrorCode.E003_INVALID_FILENAME: "Ensure filename matches pattern: {TYPE}_{NAME}_V{N}.md",
+    ErrorCode.E004_CROSS_REPO_REF: "Move artifact into input_dir or remove reference",
+    ErrorCode.E005_DEPRECATED_ARTIFACT: "Remove deprecated artifact or update its status field",
+    ErrorCode.E101_INVALID_YAML: "Check YAML syntax, ensure proper indentation",
+    ErrorCode.E102_MISSING_FIELD: "Add required field to artifact frontmatter",
+    ErrorCode.E104_INVALID_FQDN: "FQDN format: {namespace}::{artifact_code}",
+    ErrorCode.E201_MISSING_REFERENCE: "Add referenced artifact or remove reference",
+    ErrorCode.E202_CIRCULAR_DEPENDENCY: "Break dependency cycle between artifacts",
+    ErrorCode.E204_INVALID_RB_BINDING: "Ensure RB references valid CS artifact",
+    ErrorCode.E205_CT_VALIDATION_FAILED: "Check CT atom_stream and purity constraints",
+    ErrorCode.E301_WRITE_FAILED: "Check output directory permissions and disk space",
+    ErrorCode.E401_MISSING_OUTPUT: "Check materialization phase completed successfully",
+    ErrorCode.E402_UNDECLARED_OUTPUT: "Remove stale file or add to expected outputs",
+    ErrorCode.E701_ASSERTION_FAILURE: "Fix detected violations in protocol artifacts",
+    ErrorCode.E702_UNKNOWN_ASSERT: "Ensure an executor is registered for this ASSERT artifact",
+    ErrorCode.E703_MALFORMED_ASSERT: "Check ASSERT artifact against CONSTITUTION_ASSERT_V0",
+    ErrorCode.E801_TEST_DATA_MISSING: "Create TEST_DATA artifact for the CT",
+    ErrorCode.E802_CONFORMANCE_FAILURE: "Debug CT implementation to match expected behavior",
+    ErrorCode.E803_TEST_DATA_INVALID: "Fix TEST_DATA bindings to match CT inputs contract",
+}

compiler/atoms/errors.py

@@ -0,0 +1,125 @@
+"""
+Structured error model for the PGS compiler.
+
+Design:
+- Machine-readable + human-friendly
+- Phase-tagged (S1–S8)
+- Context-rich (FQDN, artifact_code, source_path)
+- Actionable messages via ERROR_SUGGESTIONS
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from compiler.atoms.error_codes import ErrorCode, ERROR_SUGGESTIONS
+
+
+class Severity(Enum):
+    """Error severity levels."""
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+@dataclass
+class CompilerError(Exception):
+    """
+    Structured error for compiler failures.
+
+    Fields:
+        code: Error code (e.g., E201_MISSING_REFERENCE)
+        message: Human-readable description
+        phase: Stage where error occurred (e.g., S1_EXTRACT)
+        fqdn_id: Fully qualified domain name (primary identity)
+        artifact_code: Short code for display/logging (not unique)
+        source_path: Path to source file if applicable
+        context: Additional debug information
+        severity: Error severity level
+    """
+
+    code: ErrorCode
+    message: str
+    phase: str
+    fqdn_id: str | None = None
+    artifact_code: str | None = None
+    source_path: Path | None = None
+    context: dict[str, Any] = field(default_factory=dict)
+    severity: Severity = Severity.ERROR
+
+    def __str__(self) -> str:
+        """String representation delegates to format()."""
+        return self.format(verbose=False)
+
+    def format(self, verbose: bool = False) -> str:
+        """
+        Format error for terminal output.
+
+        Args:
+            verbose: Include full context and suggestions
+
+        Returns:
+            Formatted error string
+        """
+        # Color codes (basic ANSI)
+        color = {
+            Severity.ERROR: "\033[91m",  # Red
+            Severity.WARNING: "\033[93m",  # Yellow
+            Severity.INFO: "\033[94m",  # Blue
+        }
+        reset = "\033[0m"
+
+        severity_color = color.get(self.severity, "")
+        severity_str = self.severity.value.upper()
+
+        # Basic format: [ERROR] E201: Message
+        basic = f"{severity_color}[{severity_str}]{reset} {self.code.value}: {self.message}"
+
+        if not verbose:
+            return basic
+
+        # Verbose format includes location, context
+        parts = [basic]
+
+        if self.source_path:
+            parts.append(f"  File: {self.source_path}")
+
+        if self.fqdn_id:
+            parts.append(f"  FQDN: {self.fqdn_id}")
+
+        if self.artifact_code:
+            parts.append(f"  Code: {self.artifact_code}")
+
+        if self.phase:
+            parts.append(f"  Phase: {self.phase}")
+
+        if self.context:
+            parts.append("  Context:")
+            for key, value in self.context.items():
+                parts.append(f"    {key}: {value}")
+
+        # Add suggestion if available
+        suggestion = self._get_suggestion()
+        if suggestion:
+            parts.append(f"  💡 Suggestion: {suggestion}")
+
+        return "\n".join(parts)
+
+    def _get_suggestion(self) -> str | None:
+        """Get actionable suggestion for fixing this error."""
+        return ERROR_SUGGESTIONS.get(self.code)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON output."""
+        return {
+            "code": self.code.value,
+            "message": self.message,
+            "phase": self.phase,
+            "fqdn_id": self.fqdn_id,
+            "artifact_code": self.artifact_code,
+            "source_path": str(self.source_path) if self.source_path else None,
+            "context": self.context,
+            "severity": self.severity.value,
+        }

compiler/atoms/fqdn.py

@@ -0,0 +1,204 @@
+"""
+FQDN (Fully Qualified Domain Name) utilities.
+
+Patch 1 Applied: FQDN is PRIMARY identity, never use artifact_code for uniqueness.
+
+FQDN Format: {namespace}::{artifact_code}
+Example: pgs_governance::CT_SCAN_ARTIFACTS_V0
+
+Design:
+- FQDN is PRIMARY identity (all references use FQDN)
+- artifact_code is display/logging ONLY (not guaranteed unique)
+- Namespace prevents collision across layers (e.g., pgs_governance, compiler)
+- Parse/build functions for deterministic construction
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class FQDN:
+    """
+    Fully Qualified Domain Name for artifact identity.
+
+    CRITICAL: This is the PRIMARY identity.
+    artifact_code alone is NOT sufficient (may collide).
+
+    IMMUTABILITY GUARANTEE:
+    - frozen=True prevents mutation
+    - Always use str(fqdn) or fqdn.fqdn for identity
+    - NEVER access .namespace or .artifact_code separately outside atoms layer
+    - Prevents accidental reversion to partial identity
+
+    Fields:
+        namespace: Package/layer namespace (e.g., "pgs_governance") [INTERNAL]
+        artifact_code: Short code (e.g., "CT_SCAN_V0") [INTERNAL]
+        fqdn: Full identifier (namespace::artifact_code) [PUBLIC]
+    """
+
+    namespace: str
+    artifact_code: str
+
+    @property
+    def fqdn(self) -> str:
+        """
+        Get full FQDN string.
+
+        This is the ONLY public interface for identity.
+        Use this, not namespace or artifact_code separately.
+        """
+        return f"{self.namespace}::{self.artifact_code}"
+
+    def __str__(self) -> str:
+        """
+        String representation is the FQDN.
+
+        Always use this for display/logging/comparison.
+        """
+        return self.fqdn
+
+    def __hash__(self) -> int:
+        """Hash by FQDN (for use in dicts/sets)."""
+        return hash(self.fqdn)
+
+    def __repr__(self) -> str:
+        """Repr is also the FQDN (not internal components)."""
+        return f"FQDN('{self.fqdn}')"
+
+
+def parse_fqdn(fqdn_str: str) -> FQDN:
+    """
+    Parse FQDN string into components.
+
+    Args:
+        fqdn_str: FQDN string (namespace::artifact_code)
+
+    Returns:
+        FQDN object
+
+    Raises:
+        ValueError: If FQDN format invalid
+
+    Examples:
+        >>> parse_fqdn("pgs_governance::CT_SCAN_V0")
+        FQDN(namespace='pgs_governance', artifact_code='CT_SCAN_V0')
+    """
+    if "::" not in fqdn_str:
+        raise ValueError(
+            f"Invalid FQDN format: '{fqdn_str}'\n"
+            f"Expected: {{namespace}}::{{artifact_code}}\n"
+            f"Example: pgs_governance::CT_SCAN_V0"
+        )
+
+    parts = fqdn_str.split("::", 1)
+    if len(parts) != 2:
+        raise ValueError(f"Invalid FQDN: '{fqdn_str}' (expected exactly one '::')")
+
+    namespace, artifact_code = parts
+
+    if not namespace:
+        raise ValueError(f"Invalid FQDN: '{fqdn_str}' (empty namespace)")
+
+    if not artifact_code:
+        raise ValueError(f"Invalid FQDN: '{fqdn_str}' (empty artifact_code)")
+
+    return FQDN(namespace=namespace, artifact_code=artifact_code)
+
+
+def build_fqdn(source_path: Path, layer_root: Path, artifact_code: str) -> FQDN:
+    """
+    Build FQDN from source path and layer root.
+
+    Derives namespace from directory structure:
+    - Namespace = layer_root.name (e.g., pgs_governance, compiler)
+
+    Args:
+        source_path: Path to artifact source file
+        layer_root: Root directory of layer
+        artifact_code: Short code (e.g., CT_SCAN_V0)
+
+    Returns:
+        FQDN object
+
+    Examples:
+        >>> build_fqdn(
+        ...     Path("/pgs/pgs_governance/registry/CT_FOO.md"),
+        ...     Path("/pgs/pgs_governance"),
+        ...     "CT_FOO_V0"
+        ... )
+        FQDN(namespace='pgs_governance', artifact_code='CT_FOO_V0')
+    """
+    # Namespace is derived from layer root directory name
+    # This ensures uniqueness across different layers/repos
+    namespace = layer_root.name
+
+    return FQDN(namespace=namespace, artifact_code=artifact_code)
+
+
+def extract_artifact_code(filename: str) -> str:
+    """
+    Extract artifact code from filename.
+
+    Args:
+        filename: Artifact filename (e.g., "CT_SCAN_V0.md")
+
+    Returns:
+        Artifact code without extension
+
+    Examples:
+        >>> extract_artifact_code("CT_SCAN_ARTIFACTS_V0.md")
+        'CT_SCAN_ARTIFACTS_V0'
+    """
+    # Remove extension
+    if filename.endswith(".md"):
+        return filename[:-3]
+    return filename
+
+
+def validate_artifact_code(code: str) -> bool:
+    """
+    Validate artifact code format.
+
+    Expected pattern: {TYPE}_{NAME}_V{VERSION}
+    Examples: CT_SCAN_V0, WF_BUILD_V1
+
+    Args:
+        code: Artifact code to validate
+
+    Returns:
+        True if valid, False otherwise
+    """
+    # Pattern: TYPE_NAME_VN (where TYPE is 2-20 uppercase letters)
+    pattern = r"^[A-Z]{2,20}_[A-Z0-9_]+_V\d+$"
+    return bool(re.match(pattern, code))
+
+
+def to_fqdn(ref: str, namespace: str) -> FQDN:
+    """
+    Normalize reference to FQDN.
+
+    CRITICAL: All references MUST be FQDN.
+    This helper converts partial references (artifact_code only) to full FQDN.
+
+    Args:
+        ref: Reference string (either "namespace::artifact_code" or "artifact_code")
+        namespace: Default namespace if ref is partial
+
+    Returns:
+        FQDN object
+
+    Examples:
+        >>> to_fqdn("pgs_governance::CT_SCAN_V0", "fallback")
+        FQDN('pgs_governance::CT_SCAN_V0')
+
+        >>> to_fqdn("CT_SCAN_V0", "pgs_governance")
+        FQDN('pgs_governance::CT_SCAN_V0')
+    """
+    if "::" in ref:
+        # Already FQDN format
+        return parse_fqdn(ref)
+    else:
+        # Partial reference (artifact_code only)
+        return FQDN(namespace=namespace, artifact_code=ref)

compiler/atoms/invariants.py

@@ -0,0 +1,106 @@
+"""
+Lightweight invariant enforcement.
+
+NOT the PGS ASSERT framework - just simple fail-fast helpers.
+
+Design:
+- Simple condition checking
+- Raises CompilerError on violation
+- No protocol semantics
+- No registry hooks
+- Just: if not condition → error
+"""
+
+from .errors import CompilerError
+
+
+def require(condition: bool, error: CompilerError) -> None:
+    """
+    Require condition to be true, raise error if false.
+
+    Lightweight assertion for fail-fast enforcement.
+    NOT PGS ASSERT framework - no protocol semantics.
+
+    Args:
+        condition: Boolean condition that must be true
+        error: Error to raise if condition is false
+
+    Raises:
+        CompilerError: If condition is false
+
+    Examples:
+        >>> require(
+        ...     fqdn_id in artifacts,
+        ...     CompilerError(
+        ...         code=ErrorCode.E201_MISSING_REFERENCE,
+        ...         message=f"Reference {fqdn_id} not found",
+        ...         phase="VALIDATE"
+        ...     )
+        ... )
+    """
+    if not condition:
+        raise error
+
+
+def require_not_none(value: any, error: CompilerError) -> any:
+    """
+    Require value is not None, raise error if None.
+
+    Args:
+        value: Value to check
+        error: Error to raise if value is None
+
+    Returns:
+        value (if not None)
+
+    Raises:
+        CompilerError: If value is None
+
+    Examples:
+        >>> config = require_not_none(
+        ...     config_dict.get("artifact_types"),
+        ...     CompilerError(
+        ...         code=ErrorCode.E902_CONFIG_ERROR,
+        ...         message="Missing required config: artifact_types",
+        ...         phase="CONFIG"
+        ...     )
+        ... )
+    """
+    if value is None:
+        raise error
+    return value
+
+
+def require_exists(path: "Path", error: CompilerError) -> "Path":
+    """
+    Require path exists, raise error if not.
+
+    Args:
+        path: Path to check
+        error: Error to raise if path doesn't exist
+
+    Returns:
+        path (if exists)
+
+    Raises:
+        CompilerError: If path doesn't exist
+
+    Examples:
+        >>> input_dir = require_exists(
+        ...     Path(args.input_dir),
+        ...     CompilerError(
+        ...         code=ErrorCode.E001_NO_ARTIFACTS,
+        ...         message=f"Input directory not found: {args.input_dir}",
+        ...         phase="DISCOVERY"
+        ...     )
+        ... )
+    """
+    from pathlib import Path
+
+    if not isinstance(path, Path):
+        path = Path(path)
+
+    if not path.exists():
+        raise error
+
+    return path