12. Configuration: The Codex

    @classmethod
    def settings_customise_sources(
        cls,
        settings_cls: type[BaseSettings],
        init_settings: PydanticBaseSettingsSource,
        env_settings: PydanticBaseSettingsSource,
        dotenv_settings: PydanticBaseSettingsSource,
        file_secret_settings: PydanticBaseSettingsSource,
    ) -> tuple[PydanticBaseSettingsSource, ...]:
        return (
            init_settings,
            env_settings,
            dotenv_settings,
            # Load from the TOML file specified in constants.py
            TomlConfigSettingsSource(settings_cls, toml_file=PATH_LYCHD_TOML),
            file_secret_settings,
        )

    @property
    def reserved_ports_map(self) -> dict[str, int]:
        """Map of Service Name -> Port."""
        return {
            "LychD Server": self.server.port,
            "Phylactery (Postgres)": self.db.port,
            "Vite (Frontend)": self.vite.port,
            "Oculus (Phoenix)": self.phoenix.ui_port,
        }

    @model_validator(mode="after")
    def check_port_conflicts(self) -> Settings:
        """Ensure no critical system ports overlap."""
        # Invert to check for duplicates: {port: [names]}
        port_map: dict[int, list[str]] = {}
        for name, port in self.reserved_ports_map.items():
            port_map.setdefault(port, []).append(name)

        # Find collisions
        errors: list[str] = []
        for port, names in port_map.items():
            if len(names) > 1:
                errors.append(f"Port {port} is claimed by multiple services: {', '.join(names)}")

        if errors:
            _msg = f"Configuration Error: {'; '.join(errors)}"
            raise ValueError(_msg)

        codex_issues = codex_permission_issues(PATH_LYCHD_TOML)
        if codex_issues:
            import warnings
            warnings.warn(
                f"codex_permissions_policy_violation: path={PATH_LYCHD_TOML} issues={codex_issues}",
                UserWarning,
                stacklevel=2,
            )

        return self


def ensure_internal_secret_fallbacks(settings: Settings) -> list[str]:
    """Ensure app/db runtime secrets exist even before Podman bind.

    This is a startup safety-net for direct process execution (development,
    tests, or any flow that boots without mounted Podman secrets). It does not
    replace bind-time Podman secret provisioning.
    """
    created: list[str] = []

    if needs_generated_secret_fallback(
        value_env_keys=("APP__SECRET_KEY", "APP_SECRET_KEY"),
        file_env_keys=("APP__SECRET_KEY_FILE", "APP_SECRET_KEY_FILE"),
        default_file=Path("/run/secrets") / settings.app.secret_key_secret,
    ):
        settings.app.set_runtime_secret_key_override(secrets.token_hex(32))
        created.append(settings.app.secret_key_secret)

    if needs_generated_secret_fallback(
        value_env_keys=("DB__PASSWORD", "DB_PASSWORD"),
        file_env_keys=("DB__PASSWORD_FILE", "DB_PASSWORD_FILE"),
        default_file=Path("/run/secrets") / settings.db.password_secret,
    ):
        settings.db.set_runtime_password_override(secrets.token_urlsafe(16))
        created.append(settings.db.password_secret)

    return created


@lru_cache(maxsize=1, typed=True)
def get_settings() -> Settings:
    settings = Settings()
    ensure_internal_secret_fallbacks(settings)
    return settings

RUNE_PATH_PART_PATTERN = re.compile(r"^[a-z0-9](?:[a-z0-9_-]{0,48}[a-z0-9])?$")


class RuneConfig(BaseModel, ABC):
    """Base for TOML-backed Codex runes.

    A rune is one validated TOML config document under
    ``lychd.system.constants.PATH_RUNES_DIR``. Subclasses define TOML fields;
    this base validates class-level placement metadata.
    """

    model_config = ConfigDict(extra="forbid")

    def __init_subclass__(cls, **kwargs: Any) -> None:
        """Validate rune class metadata when a rune subclass is declared.

        Args:
            **kwargs: Extra subclass initialization keywords forwarded to
                ``BaseModel``.

        Raises:
            ValueError: If the subclass declares an invalid ``path_fragment``.
            TypeError: If ``path_fragment`` is not a ``Path`` or rune ancestry
                is ambiguous.

        """
        super().__init_subclass__(**kwargs)

        # ``ClassVar`` values are inherited. ``getattr(cls, "path_fragment")``
        # would therefore let a child silently reuse its parent suffix, producing
        # the wrong anchor. Require a class-local declaration instead.
        if "path_fragment" not in cls.__dict__:
            msg = f"Rune '{cls.__name__}' declares no path_fragment."
            raise ValueError(msg)
        path_fragment: Any = cls.__dict__["path_fragment"]

        # The fragment is a relative ``Path`` suffix, not a filesystem root.
        # Loader/writer code owns the absolute root via ``PATH_RUNES_DIR``.
        if not isinstance(path_fragment, Path):
            msg = f"Rune '{cls.__name__}' declares non-Path path_fragment {path_fragment!r}."
            raise TypeError(msg)
        if path_fragment.is_absolute() or path_fragment == Path():
            msg = f"Rune '{cls.__name__}' declares invalid path_fragment '{path_fragment}'. Expected relative path fragment."
            raise ValueError(msg)

        # Validate every fragment part because a fragment may contain more than
        # one suffix component. The pattern rejects traversal, uppercase drift,
        # spaces, and filesystem-looking surprises.
        for part in path_fragment.parts:
            if not RUNE_PATH_PART_PATTERN.fullmatch(part):
                pattern = RUNE_PATH_PART_PATTERN.pattern
                msg = f"Rune '{cls.__name__}' declares invalid path_fragment part '{part}'. Expected pattern: {pattern}"
                raise ValueError(msg)

        # The final path is a single parent chain plus this suffix. Multiple
        # RuneConfig parents would make that path ambiguous. Mixins that only
        # share fields should inherit BaseModel or object, not RuneConfig.
        rune_parents = [
            base for base in cls.__bases__ if issubclass(base, RuneConfig) and base is not RuneConfig
        ]
        if len(rune_parents) > 1:
            names = ", ".join(parent.__name__ for parent in rune_parents)
            msg = f"Rune '{cls.__name__}' declares multiple rune parents: {names}."
            raise TypeError(msg)
        parent = rune_parents[0] if rune_parents else None

        # Store the final path under PATH_RUNES_DIR, still relative. RuneConfig
        # computes schema-local placement; loaders/writers choose the root.
        cls.relative_path = path_fragment if parent is None else parent.relative_path / path_fragment

class RuneConfig(BaseModel, ABC):
    """Base for TOML-backed Codex runes.

    A rune is one validated TOML config document under
    ``lychd.system.constants.PATH_RUNES_DIR``. Subclasses define TOML fields;
    this base validates class-level placement metadata.
    """

    model_config = ConfigDict(extra="forbid")

    def __init_subclass__(cls, **kwargs: Any) -> None:
        """Validate rune class metadata when a rune subclass is declared.

        Args:
            **kwargs: Extra subclass initialization keywords forwarded to
                ``BaseModel``.

        Raises:
            ValueError: If the subclass declares an invalid ``path_fragment``.
            TypeError: If ``path_fragment`` is not a ``Path`` or rune ancestry
                is ambiguous.

        """
        super().__init_subclass__(**kwargs)

        # ``ClassVar`` values are inherited. ``getattr(cls, "path_fragment")``
        # would therefore let a child silently reuse its parent suffix, producing
        # the wrong anchor. Require a class-local declaration instead.
        if "path_fragment" not in cls.__dict__:
            msg = f"Rune '{cls.__name__}' declares no path_fragment."
            raise ValueError(msg)
        path_fragment: Any = cls.__dict__["path_fragment"]

        # The fragment is a relative ``Path`` suffix, not a filesystem root.
        # Loader/writer code owns the absolute root via ``PATH_RUNES_DIR``.
        if not isinstance(path_fragment, Path):
            msg = f"Rune '{cls.__name__}' declares non-Path path_fragment {path_fragment!r}."
            raise TypeError(msg)
        if path_fragment.is_absolute() or path_fragment == Path():
            msg = f"Rune '{cls.__name__}' declares invalid path_fragment '{path_fragment}'. Expected relative path fragment."
            raise ValueError(msg)

        # Validate every fragment part because a fragment may contain more than
        # one suffix component. The pattern rejects traversal, uppercase drift,
        # spaces, and filesystem-looking surprises.
        for part in path_fragment.parts:
            if not RUNE_PATH_PART_PATTERN.fullmatch(part):
                pattern = RUNE_PATH_PART_PATTERN.pattern
                msg = f"Rune '{cls.__name__}' declares invalid path_fragment part '{part}'. Expected pattern: {pattern}"
                raise ValueError(msg)

        # The final path is a single parent chain plus this suffix. Multiple
        # RuneConfig parents would make that path ambiguous. Mixins that only
        # share fields should inherit BaseModel or object, not RuneConfig.
        rune_parents = [
            base for base in cls.__bases__ if issubclass(base, RuneConfig) and base is not RuneConfig
        ]
        if len(rune_parents) > 1:
            names = ", ".join(parent.__name__ for parent in rune_parents)
            msg = f"Rune '{cls.__name__}' declares multiple rune parents: {names}."
            raise TypeError(msg)
        parent = rune_parents[0] if rune_parents else None

        # Store the final path under PATH_RUNES_DIR, still relative. RuneConfig
        # computes schema-local placement; loaders/writers choose the root.
        cls.relative_path = path_fragment if parent is None else parent.relative_path / path_fragment

    path_fragment: ClassVar[Path]
    """Relative suffix appended after the parent rune class's ``relative_path``."""

    relative_path: ClassVar[Path]
    """Computed path under ``PATH_RUNES_DIR`` where this class's TOMLs live."""

    source_file: Path | None = Field(default=None, exclude=True, repr=False)
    """Absolute source TOML file that produced this validated instance."""

"""Typing protocols for objects that retain rune provenance."""

from __future__ import annotations

from typing import Protocol, runtime_checkable

from lychd.config.runes.base import RuneConfig


@runtime_checkable
class Runic[T: RuneConfig](Protocol):
    """Protocol for objects configured by a Codex Rune.

    Any runtime object with ``rune: T`` satisfies this protocol structurally.
    Such objects are servants of the Codex: they retain the validated config
    that shaped them, but they are not themselves rune schemas.
    """

    @property
    def rune(self) -> T:
        """Return the validated source Rune.

        Returns:
            The ``RuneConfig`` instance used as this object's configuration
            provenance.

        """

    def __init__(self, runes_dir: Path | None = None) -> None:
        """Create a loader for a concrete rune root.

        Args:
            runes_dir: Optional root directory to scan. Defaults to
                ``PATH_RUNES_DIR``.

        """
        self._runes_dir = runes_dir or PATH_RUNES_DIR

    def load_all(self, schemas: Sequence[type[RuneConfig]]) -> list[RuneConfig]:
        """Load and validate all instances for the provided rune classes.

        Args:
            schemas: Rune classes whose anchors should be scanned.

        Returns:
            Validated rune instances bound to their source filenames.

        Raises:
            ValueError: If TOML parsing, branch-file enforcement, identity
                validation, or Pydantic model validation fails.

        """
        loaded: list[RuneConfig] = []

        for cls in schemas:
            loaded.extend(self._load_class_instances(cls))

        logger.debug("runes_loaded", count=len(loaded), classes=[c.__name__ for c in schemas])
        return loaded

    def _load_class_instances(self, cls: type[RuneConfig]) -> list[RuneConfig]:
        """Load every TOML instance owned by one rune class.

        Args:
            cls: Rune class whose anchor should be scanned.

        Returns:
            Validated instances for ``cls``.

        Raises:
            ValueError: If a branch rune owns TOML files, or if payload/identity
                validation fails.

        """
        files = self._candidate_files(cls)
        if cls.__subclasses__():
            if files:
                msg = f"Branch rune class '{cls.__name__}' cannot own TOML files in '{self._anchor_dir(cls)}'."
                raise ValueError(msg)
            return []

        instances: list[RuneConfig] = []

        for file_path in files:
            payload = self._read_payload(file_path, cls)
            instance = cls.model_validate(payload)
            instance.source_file = file_path
            instances.append(instance)

        self._assert_unique_identity(files)
        return instances

    def _candidate_files(self, cls: type[RuneConfig]) -> list[Path]:
        """Find candidate TOML files for a rune anchor.

        Args:
            cls: Rune class whose anchor should be scanned.

        Returns:
            Sorted TOML files directly in the rune class's anchor.

        """
        anchor = self._anchor_dir(cls)
        if not anchor.exists():
            return []

        return sorted(anchor.glob("*.toml"))

    def _anchor_dir(self, cls: type[RuneConfig]) -> Path:
        """Resolve the active filesystem anchor for one rune class.

        Args:
            cls: Rune class whose anchor should be resolved.

        Returns:
            Absolute directory under this loader's rune root.

        """
        return self._runes_dir / cls.relative_path

    def _read_payload(self, file_path: Path, cls: type[RuneConfig]) -> dict[str, Any]:
        """Read one TOML payload and enforce rune envelope rules.

        Args:
            file_path: TOML file to read.
            cls: Rune class used to decide whether legacy envelope keys are
                allowed.

        Returns:
            Parsed TOML payload with string keys.

        Raises:
            ValueError: If the file is unreadable, malformed, or uses a legacy
                ``[model]`` envelope for a rune class that does not declare a
                ``model`` field.

        """
        try:
            parsed = tomllib.loads(file_path.read_text(encoding="utf-8"))
        except tomllib.TOMLDecodeError as exc:
            msg = f"Malformed TOML in '{file_path}'."
            raise ValueError(msg) from exc
        except OSError as exc:
            msg = f"Could not read '{file_path}'."
            raise ValueError(msg) from exc

        content: dict[str, Any] = {str(k): v for k, v in parsed.items()}
        if "model" in content and isinstance(content["model"], dict) and "model" not in cls.model_fields:
            msg = (
                f"File '{file_path}' uses legacy '[model]' envelope syntax. "
                "Rune payload must be written at TOML top level."
            )
            raise ValueError(msg)

        return content

    def _assert_unique_identity(self, files: list[Path]) -> None:
        """Reject duplicate identities after path normalization.

        Args:
            files: Candidate TOML files for that rune class.

        Raises:
            ValueError: If two files derive the same rune-local identity.

        """
        seen: set[str] = set()

        for file_path in files:
            identity = self._instance_id_from_path(file_path)
            if identity in seen:
                msg = f"Duplicate identity detected: '{identity}'."
                raise ValueError(msg)
            seen.add(identity)

    def _instance_id_from_path(self, file_path: Path) -> str:
        """Derive a stable instance identity from a TOML path.

        Args:
            file_path: TOML file path under this loader's rune root.

        Returns:
            Rune-root-relative path without the TOML suffix.

        Raises:
            ValueError: If ``file_path`` is outside this loader's rune root.

        """
        rel = file_path.relative_to(self._runes_dir)
        return str(rel.with_suffix(""))

        """
        if not extensions_path.exists():
            return

        for item in extensions_path.iterdir():
            if item.suffix == ".py" and not item.name.startswith("_"):
                self._load_and_translate(item)

    def _load_and_translate(self, file_path: Path) -> None:
        """Load one extension module and register rune-shaped classes.

        Args:
            file_path: Python source module path to load.

        """
        module_name = file_path.stem

        # Binary modules are deliberately excluded from this direct runtime path.
        # They need a Forge manifest and platform validation before import.
        loader = importlib.machinery.SourceFileLoader(module_name, str(file_path))

        spec = importlib.util.spec_from_loader(module_name, loader)
        if not spec or not spec.loader:
            return

        module = importlib.util.module_from_spec(spec)
        spec.loader.exec_module(module)

        # 2. Scan the isolated module for rune-shaped classes.
        for attr_name in dir(module):
            if attr_name.startswith("_"):
                continue

            obj = getattr(module, attr_name)

            # We are looking for Classes that match the shape, not instances.
            # issubclass() fails for Protocols with non-method members.
            if isinstance(obj, type):
                has_path = hasattr(obj, "relative_path")
                has_validate = hasattr(obj, "model_validate")
                if has_path and has_validate:
                    self.codex_loader.register_schema(obj)

    def discover_classes(self) -> list[type[RuneConfig]]:
        """Discover loadable rune classes.

        Returns:
            Deterministically sorted rune classes accepted by the discovery
            filters.

        """
        self._import_extension_packages()

        discovered: set[type[RuneConfig]] = set()
        self._collect_subclasses(RuneConfig, discovered)

        # Provisional Crypt source modules register rune-shaped classes here.
        external_schemas: set[type[RuneConfig]] = set()

        class SchemaCollector:
            def register_schema(self, schema: type[RuneConfig]) -> None:
                external_schemas.add(schema)

        loader = CryptSourceLoader(SchemaCollector())
        loader.scan_extensions(self._extensions_path)

        all_schemas = discovered | external_schemas
        filtered = [cls for cls in all_schemas if self._is_allowed_schema_module(cls, external=cls in external_schemas)]
        return sorted(filtered, key=lambda cls: (cls.__module__, cls.__qualname__))

    def _import_extension_packages(self) -> None:
        """Import configured extension package roots before subclass traversal.

        Raises:
            ImportError: If an extension package or module cannot be imported.

        """
        for package_name in self._extension_packages:
            package = importlib.import_module(package_name)
            package_path = getattr(package, "__path__", None)
            if package_path is None:
                continue
            for module in pkgutil.walk_packages(package_path, f"{package.__name__}."):
                importlib.import_module(module.name)

    def _collect_subclasses(self, parent: type[RuneConfig], discovered: set[type[RuneConfig]]) -> None:
        """Recursively collect RuneConfig subclasses.

        Args:
            parent: Rune class whose subclasses should be walked.
            discovered: Mutable set receiving discovered subclasses.

        """
        for subclass in parent.__subclasses__():
            self._collect_subclasses(subclass, discovered)
            discovered.add(subclass)

    def _is_allowed_schema_module(self, cls: type[RuneConfig], *, external: bool = False) -> bool:
        """Return whether a rune class may enter the loader set.

        Args:
            cls: Candidate rune class from subclass or Crypt source discovery.
            external: Whether the class came from Crypt source discovery.

        Returns:
            ``True`` when the class exposes the rune discovery shape or belongs to
            an allowed package.

        """
        if external and hasattr(cls, "relative_path") and hasattr(cls, "model_validate"):
            raw_path = getattr(cls, "relative_path", None)
            if raw_path is not None and not isinstance(raw_path, Path):
                msg = f"Rune '{cls.__name__}' declares non-Path relative_path {raw_path!r}."
                raise TypeError(msg)
            if raw_path is None:
                msg = f"Rune '{cls.__name__}' declares no relative_path."
                raise ValueError(msg)
            if raw_path.is_absolute() or raw_path == Path():
                msg = f"Rune '{cls.__name__}' declares invalid relative_path '{raw_path}'."
                raise ValueError(msg)
            for part in raw_path.parts:
                if not RUNE_PATH_PART_PATTERN.fullmatch(part):
                    msg = f"Rune '{cls.__name__}' declares invalid relative_path part '{part}'."
                    raise ValueError(msg)
            return True

        module = cls.__module__
        return any(module == package or module.startswith(f"{package}.") for package in self._allowed_packages)

    """Writes rune sample TOMLs and initializes rune anchor directories."""

    def __init__(self, runes_dir: Path | None = None) -> None:
        """Create a writer for runes under a specific root.

        Args:
            runes_dir: Optional root directory to write. Defaults to
                ``PATH_RUNES_DIR``.

        """
        self._runes_dir = runes_dir or PATH_RUNES_DIR

    def initialize_anchors(self, schemas: list[type[RuneConfig]]) -> None:
        """Ensure all rune anchor directories exist."""
        for schema in schemas:
            anchor = self._anchor_dir(schema)
            anchor.mkdir(parents=True, exist_ok=True)
            logger.debug("anchor_initialized", schema=schema.__name__, anchor=str(anchor))

    def inscribe_samples(self, schemas: list[type[RuneConfig]]) -> list[Path]:
        """Write one sample TOML per rune class when no files exist yet."""
        created: list[Path] = []

        for schema in schemas:
            target = self._target_sample_file(schema)
            if target is None:
                continue

            target.parent.mkdir(parents=True, exist_ok=True)
            target.write_text(self._render_sample(schema), encoding="utf-8")
            created.append(target)
            logger.info("rune_sample_inscribed", schema=schema.__name__, path=str(target))

        return created

    def _target_sample_file(self, schema: type[RuneConfig]) -> Path | None:
        """Return sample target path if schema has no existing TOML instances."""
        if schema.__subclasses__():
            return None

        file_name = self._default_file_name(schema)

        anchor = self._anchor_dir(schema)
        existing = list(anchor.glob("*.toml")) if anchor.exists() else []
        if existing:
            return None

        return anchor / file_name

    def _anchor_dir(self, schema: type[RuneConfig]) -> Path:
        """Resolve the active filesystem anchor for one rune class.

        Args:
            schema: Rune class whose anchor should be resolved.

        Returns:
            Absolute directory under this writer's rune root.

        """
        return self._runes_dir / schema.relative_path

    def _default_file_name(self, schema: type[RuneConfig]) -> str:
        """Derive the generated TOML sample filename for a rune class.

        Args:
            schema: Rune class needing a generated sample filename.

        Returns:
            The lowercase rune class name with a ``.toml`` suffix.

        """
        return f"{schema.__name__.lower()}.toml"

    def _render_sample(self, schema: type[RuneConfig]) -> str:
        lines: list[str] = []

        for field_name, field_info in schema.model_fields.items():
            if field_name == "source_file":
                continue

            if field_info.description:
                lines.append(f"# {field_info.description}")

            if field_info.default is not PydanticUndefined:
                lines.append(f"# default: {field_info.default!r}")
            elif field_info.default_factory is not None:
                lines.append("# default: <factory>")

            value = self._sample_value(field_info.annotation, required=field_info.is_required())
            assignment = f"{field_name} = {value}"

            if field_info.is_required():
                lines.append(assignment)
            else:
                # Optional/defaulted fields are documented but commented out.
                lines.append(f"# {assignment}")

            lines.append("")

        return "\n".join(lines).rstrip() + "\n"