from __future__ import annotations
from pathlib import Path


def get_core_head() -> str:
    """Return the current head revision ID of the core migration scripts.

    Called at migration authoring time (when running ``alembic revision``),
    not at application runtime. The returned ID should be captured statically
    in a plugin's ``depends_on`` field.
    """
    from alembic.config import Config
    from alembic.script import ScriptDirectory

    migrations_dir = Path(__file__).parent.parent / "migrations"
    cfg = Config()
    cfg.set_main_option("script_location", str(migrations_dir))
    script = ScriptDirectory.from_config(cfg)
    heads = script.get_heads()
    if len(heads) != 1:
        raise RuntimeError(
            f"Expected exactly 1 core migration head, got {len(heads)}: {heads}"
        )
    return heads[0]