psyclaw 0.27.23 → 0.28.1

package/vendor/ars/tools/release-discipline/scripts/_release_doc_alignment_schema.py

@@ -0,0 +1,1011 @@
+"""Manifest schema loading and validation.
+
+Cross-repo agnostic per INVARIANT 12. No domain assumptions, no language
+literals (INVARIANT 3, 20). Pure schema + path safety logic; no network,
+no file writes (INVARIANT 4, 17).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class ManifestError(Exception):
+    kind: str
+    message: str
+    field: str | None = None
+    reason: str | None = None
+
+    def __str__(self) -> str:
+        base = f"{self.kind}: {self.message}"
+        if self.field:
+            base += f" (field={self.field})"
+        if self.reason:
+            base += f" (reason={self.reason})"
+        return base
+
+
+def _load_manifest_toml(manifest_path: Path) -> dict[str, Any]:
+    """Existence + TOML-decode prongs of manifest loading (shared by both
+    validators' loaders)."""
+    if not manifest_path.exists():
+        raise ManifestError(
+            kind="manifest_not_found",
+            message=f"manifest file not found: {manifest_path}",
+        )
+    try:
+        with open(manifest_path, "rb") as fh:
+            return tomllib.load(fh)
+    except tomllib.TOMLDecodeError as exc:
+        raise ManifestError(
+            kind="manifest_invalid_toml",
+            message=f"manifest is not valid TOML: {exc}",
+        ) from exc
+
+
+def load_manifest(manifest_path: Path) -> dict[str, Any]:
+    """Load and minimally validate the manifest TOML.
+
+    Raises ManifestError with .kind set per §10 failure catalog.
+    """
+    manifest_path = Path(manifest_path)
+    data = _load_manifest_toml(manifest_path)
+
+    _check_unknown_keys(data)
+    _check_value_types(data)
+    _check_package_schema(data)
+    _check_file_entries(data)
+    _check_package_uniqueness(data)
+
+    if "changelog_path" not in data:
+        raise ManifestError(
+            kind="manifest_required_field_missing",
+            message="manifest missing required field: changelog_path",
+            field="changelog_path",
+        )
+
+    _check_all_paths(data, manifest_path)
+    _check_all_templates(data)
+    _check_scanner_markers(data)
+    _check_changelog_pattern(data)
+    _check_pattern_against_comment_marker(data)
+
+    return data
+
+
+# Allow-list of top-level keys + per-section keys. Per INVARIANT 14, any key
+# outside these is a hard error. Ordered tuples (not sets) so that key-driven
+# validation loops raise deterministically (INVARIANT 4) and so the same
+# catalog drives both _check_unknown_keys and _check_value_types — a key added
+# here is automatically type-checked.
+_TOP_LEVEL_KEYS: tuple[str, ...] = (
+    "changelog_path",
+    "changelog_entry_pattern",
+    "suite",
+    "changelog",
+    "file",
+    "package",
+)
+_SUITE_KEYS: tuple[str, ...] = ("latest", "latest_date")
+_SCANNER_MARKER_KEYS: tuple[str, ...] = (
+    "fence_marker",
+    "comment_open",
+    "comment_close",
+)
+_CHANGELOG_KEYS: tuple[str, ...] = _SCANNER_MARKER_KEYS + ("near_miss_whitelist",)
+_FILE_KEYS: tuple[str, ...] = (
+    "path",
+    "release_block_form",
+    "badge_template",
+    "tag_url_template",
+    "last_updated_template",
+)
+_PACKAGE_KEYS: tuple[str, ...] = ("path", "type", "key", "pattern")
+
+
+_VALID_PACKAGE_TYPES: set[str] = {"toml", "json", "regex"}
+
+_TEMPLATE_FIELDS: tuple[str, ...] = (
+    "release_block_form",
+    "badge_template",
+    "tag_url_template",
+    "last_updated_template",
+)
+
+_TEMPLATE_VAR_RE = re.compile(r"\{([^{}]*)\}")
+_ALLOWED_VARS: frozenset[str] = frozenset({"version", "date"})
+
+
+def _check_template_format(template: str, *, field: str) -> None:
+    """Raise ManifestError(template_format_error) if template has unknown vars
+    or unclosed braces. Allowed: {version}, {date}; any other {...} fails.
+    Caller must guarantee template is not None (see _check_all_templates).
+    """
+    # Quick unbalanced-brace check: count { vs } and matched pairs via the regex.
+    opens = template.count("{")
+    closes = template.count("}")
+    if opens != closes:
+        raise ManifestError(
+            kind="template_format_error",
+            message=f"template has unbalanced braces: {template!r}",
+            field=field,
+        )
+    for match in _TEMPLATE_VAR_RE.finditer(template):
+        name = match.group(1)
+        if name not in _ALLOWED_VARS:
+            raise ManifestError(
+                kind="template_format_error",
+                message=f"template uses unknown variable {{{name}}}: {template!r}",
+                field=field,
+            )
+
+
+def _require_str(value: Any, *, field: str) -> None:
+    if value is not None and not isinstance(value, str):
+        raise ManifestError(
+            kind="manifest_invalid_type",
+            message=f"{field} must be a string, got {type(value).__name__}",
+            field=field,
+        )
+
+
+def _check_value_types(data: dict[str, Any]) -> None:
+    """Validate scalar value types for known keys (manifest_invalid_type).
+
+    Must run after _check_unknown_keys (which guarantees section/entry
+    container shapes) and before every other check: downstream code assumes
+    correct Python types, so a wrong-typed TOML value (e.g. a float where a
+    version string is expected) would otherwise surface as an uncaught
+    TypeError/AttributeError deep inside a check instead of a structured error.
+
+    Driven by the same key catalogs as _check_unknown_keys; every known key is
+    a string except changelog.near_miss_whitelist (array of strings).
+    """
+    _require_str(data.get("changelog_path"), field="changelog_path")
+    _require_str(data.get("changelog_entry_pattern"), field="changelog_entry_pattern")
+
+    suite = data.get("suite") or {}
+    for key in _SUITE_KEYS:
+        _require_str(suite.get(key), field=f"suite.{key}")
+
+    cs = data.get("changelog") or {}
+    for key in _SCANNER_MARKER_KEYS:
+        _require_str(cs.get(key), field=f"changelog.{key}")
+    whitelist = cs.get("near_miss_whitelist")
+    if whitelist is not None:
+        if not isinstance(whitelist, list) or any(
+            not isinstance(item, str) for item in whitelist
+        ):
+            raise ManifestError(
+                kind="manifest_invalid_type",
+                message="changelog.near_miss_whitelist must be an array of strings",
+                field="changelog.near_miss_whitelist",
+            )
+
+    for idx, entry in enumerate(data.get("file", [])):
+        for key in _FILE_KEYS:
+            _require_str(entry.get(key), field=f"file[{idx}].{key}")
+
+    for idx, entry in enumerate(data.get("package", [])):
+        for key in _PACKAGE_KEYS:
+            _require_str(entry.get(key), field=f"package[{idx}].{key}")
+
+
+def _check_all_templates(data: dict[str, Any]) -> None:
+    """Validate all template fields in [[file]] entries (INVARIANT 21)."""
+    for idx, entry in enumerate(data.get("file", [])):
+        for tf in _TEMPLATE_FIELDS:
+            value = entry.get(tf)
+            if value is not None:
+                _check_template_format(value, field=f"file[{idx}].{tf}")
+
+
+_DEFAULT_CHANGELOG: dict[str, Any] = {
+    "fence_marker": "```",
+    "comment_open": "<!--",
+    "comment_close": "-->",
+    "near_miss_whitelist": ["Unreleased", "unreleased", "TBD", "Pending"],
+}
+_DEFAULT_CHANGELOG_PATTERN: str = (
+    r"^## \[(?P<version>\S+)\] - (?P<date>\d{4}-\d{2}-\d{2})\s*$"
+)
+
+
+def changelog_settings(data: dict[str, Any]) -> dict[str, Any]:
+    """Return effective changelog settings (defaults merged with manifest overrides).
+
+    Caller should pass the dict returned by load_manifest (validated). Returned
+    dict is a deep-enough copy that mutating the result (incl. the
+    near_miss_whitelist list) does NOT poison the module-level _DEFAULT_CHANGELOG.
+    """
+    settings = dict(_DEFAULT_CHANGELOG)
+    settings["near_miss_whitelist"] = list(settings["near_miss_whitelist"])
+    settings.update(data.get("changelog") or {})
+    return settings
+
+
+def _check_regex(
+    pattern_text: str,
+    *,
+    required_groups: tuple[str, ...],
+    kind_invalid: str,
+    kind_missing: str,
+    field: str,
+) -> None:
+    """Validate that a manifest-declared regex compiles (re.MULTILINE) and
+    contains all required named groups. Shared by the changelog-pattern and
+    package-pattern checks so both fail at manifest-parse with their
+    respective §10 kinds."""
+    try:
+        compiled = re.compile(pattern_text, re.MULTILINE)
+    except re.error as exc:
+        raise ManifestError(
+            kind=kind_invalid,
+            message=f"{field} does not compile: {exc}",
+            field=field,
+        ) from exc
+    missing = [g for g in required_groups if g not in compiled.groupindex]
+    if missing:
+        raise ManifestError(
+            kind=kind_missing,
+            message=f"{field} must contain named group(s): {', '.join(missing)}",
+            field=field,
+        )
+
+
+def _check_changelog_pattern(data: dict[str, Any]) -> None:
+    """Validate an explicit changelog_entry_pattern at manifest-parse time.
+
+    The default pattern (used when the key is absent) is known-good, so only
+    a manifest-declared override is checked."""
+    pattern_text = data.get("changelog_entry_pattern")
+    if pattern_text is None:
+        return
+    _check_regex(
+        pattern_text,
+        required_groups=("version", "date"),
+        kind_invalid="changelog_regex_invalid",
+        kind_missing="changelog_regex_missing_groups",
+        field="changelog_entry_pattern",
+    )
+
+
+def _check_scanner_markers(data: dict[str, Any]) -> None:
+    cs = data.get("changelog") or {}
+    for name in _SCANNER_MARKER_KEYS:
+        if name in cs and cs[name] == "":
+            raise ManifestError(
+                kind=f"{name}_empty",
+                message=f"[changelog].{name} must not be empty",
+                field=f"changelog.{name}",
+            )
+
+
+def _check_pattern_against_comment_marker(data: dict[str, Any]) -> None:
+    pattern = data.get("changelog_entry_pattern") or _DEFAULT_CHANGELOG_PATTERN
+    cs = changelog_settings(data)
+    for marker_field in ("comment_open", "comment_close"):
+        if cs[marker_field] in pattern:
+            raise ManifestError(
+                kind="changelog_pattern_uses_comment_marker",
+                message=(
+                    f"changelog_entry_pattern contains {marker_field} literal "
+                    f"({cs[marker_field]!r}); scanner strips comments before matching, "
+                    f"so this pattern would never match"
+                ),
+                field="changelog_entry_pattern",
+            )
+
+
+def render_template(template: str, *, version: str, date: str | None) -> str | None:
+    """Render a template with {version}/{date} substitutions.
+
+    Returns None if the template references {date} but date is None — callers
+    should emit a WARN (template_uses_date_but_date_unavailable) and skip the
+    check per INVARIANT 21 + §10.
+    """
+    if "{date}" in template and date is None:
+        return None
+    return template.replace("{version}", version).replace("{date}", date or "")
+
+
+def _check_path_shape(declared: str, *, field: str) -> Path:
+    """Filesystem-free path-shape prongs of INVARIANT 13: non-empty, relative,
+    no '..' segments. Returns Path(declared). Shared by single-file path
+    validation (_check_path, which adds resolve/exists checks) and glob-pattern
+    validation (shape only — a glob is not a single existing file)."""
+    if declared is None or declared == "":
+        raise ManifestError(
+            kind="path_unsafe",
+            message=f"path is empty for field {field}",
+            field=field,
+            reason="empty",
+        )
+
+    raw = Path(declared)
+    if raw.is_absolute():
+        raise ManifestError(
+            kind="path_unsafe",
+            message=f"path is absolute: {declared}",
+            field=field,
+            reason="absolute",
+        )
+
+    if ".." in raw.parts:
+        raise ManifestError(
+            kind="path_unsafe",
+            message=f"path contains '..': {declared}",
+            field=field,
+            reason="traversal",
+        )
+    return raw
+
+
+def _check_path(declared: str, *, field: str, manifest_parent: Path) -> Path:
+    """Validate a single manifest-declared path.
+
+    Returns the resolved Path on success. Raises ManifestError(kind="path_unsafe")
+    with reason sub-field on failure, per INVARIANT 13.
+    """
+    raw = _check_path_shape(declared, field=field)
+
+    parent_resolved = manifest_parent.resolve()
+    candidate = (manifest_parent / raw).resolve()
+    try:
+        candidate.relative_to(parent_resolved)
+    except ValueError:
+        raise ManifestError(
+            kind="path_unsafe",
+            message=f"path resolves outside manifest parent: {declared} -> {candidate}",
+            field=field,
+            reason="symlink_escape",
+        ) from None
+
+    if not candidate.exists():
+        raise ManifestError(
+            kind="path_unsafe",
+            message=f"path does not exist: {declared} (resolved to {candidate})",
+            field=field,
+            reason="not_found",
+        )
+    if candidate.is_dir():
+        raise ManifestError(
+            kind="path_unsafe",
+            message=f"path is a directory, expected file: {declared}",
+            field=field,
+            reason="directory",
+        )
+
+    return candidate
+
+
+def _check_all_paths(data: dict[str, Any], manifest_path: Path) -> None:
+    """Validate all declared paths in the manifest (INVARIANT 13)."""
+    parent = manifest_path.parent
+    _check_path(data["changelog_path"], field="changelog_path", manifest_parent=parent)
+    for idx, entry in enumerate(data.get("file", [])):
+        _check_path(entry.get("path"), field=f"file[{idx}].path", manifest_parent=parent)
+    for idx, entry in enumerate(data.get("package", [])):
+        _check_path(entry.get("path"), field=f"package[{idx}].path", manifest_parent=parent)
+
+
+def _check_file_entries(data: dict[str, Any]) -> None:
+    """Raise ManifestError for missing path, empty, or duplicate [[file]] entries (INVARIANT 15)."""
+    seen: set[str] = set()
+    for idx, entry in enumerate(data.get("file", [])):
+        path = entry.get("path")
+        if path is None:
+            raise ManifestError(
+                kind="file_field_missing",
+                message=f"[[file]] entry {idx} missing required field: path",
+                field=f"file[{idx}].path",
+            )
+        if not any(entry.get(f) for f in _TEMPLATE_FIELDS):
+            raise ManifestError(
+                kind="empty_file_entry",
+                message=(
+                    f"[[file]] entry {idx} (path={path!r}) has no template fields. "
+                    f"At least one of {list(_TEMPLATE_FIELDS)} must be set."
+                ),
+                field=f"file[{idx}]",
+            )
+        if path in seen:
+            raise ManifestError(
+                kind="duplicate_file_path",
+                message=f"[[file]] path appears more than once: {path}",
+                field=f"file[{idx}].path",
+            )
+        seen.add(path)
+
+
+def _check_package_uniqueness(data: dict[str, Any]) -> None:
+    """Raise ManifestError for duplicate [[package]] paths (INVARIANT 15)."""
+    seen: set[str | None] = set()
+    for idx, entry in enumerate(data.get("package", [])):
+        path = entry.get("path")
+        if path in seen:
+            raise ManifestError(
+                kind="duplicate_package_path",
+                message=f"[[package]] path appears more than once: {path}",
+                field=f"package[{idx}].path",
+            )
+        seen.add(path)
+
+
+def _check_package_schema(data: dict[str, Any]) -> None:
+    """Validate type discriminator and field exclusivity for [[package]] entries."""
+    for idx, entry in enumerate(data.get("package", [])):
+        if entry.get("path") is None:
+            raise ManifestError(
+                kind="package_field_missing",
+                message=f"[[package]] entry {idx} missing required field: path",
+                field=f"package[{idx}].path",
+            )
+        ptype = entry.get("type")
+        if ptype is None:
+            raise ManifestError(
+                kind="package_field_missing",
+                message=f"[[package]] entry {idx} missing required field: type",
+                field=f"package[{idx}].type",
+            )
+        if ptype not in _VALID_PACKAGE_TYPES:
+            raise ManifestError(
+                kind="package_type_invalid",
+                message=f"[[package]] entry {idx} type must be one of {sorted(_VALID_PACKAGE_TYPES)}, got: {ptype}",
+                field=f"package[{idx}].type",
+            )
+        has_key = "key" in entry
+        has_pattern = "pattern" in entry
+        if ptype in ("toml", "json"):
+            if not has_key:
+                raise ManifestError(
+                    kind="package_field_missing",
+                    message=f'[[package]] entry {idx} with type="{ptype}" requires "key"',
+                    field=f"package[{idx}].key",
+                )
+            if has_pattern:
+                raise ManifestError(
+                    kind="package_field_conflict",
+                    message=f'[[package]] entry {idx} with type="{ptype}" must not set "pattern"',
+                    field=f"package[{idx}].pattern",
+                )
+        elif ptype == "regex":
+            if not has_pattern:
+                raise ManifestError(
+                    kind="package_field_missing",
+                    message=f'[[package]] entry {idx} with type="regex" requires "pattern"',
+                    field=f"package[{idx}].pattern",
+                )
+            if has_key:
+                raise ManifestError(
+                    kind="package_field_conflict",
+                    message=f'[[package]] entry {idx} with type="regex" must not set "key"',
+                    field=f"package[{idx}].key",
+                )
+            _check_regex(
+                entry["pattern"],
+                required_groups=("version",),
+                kind_invalid="package_pattern_invalid",
+                kind_missing="package_pattern_missing_group",
+                field=f"package[{idx}].pattern",
+            )
+
+
+_BARE_VERSION_RE = re.compile(r"^\d+(?:\.\d+)+(?:[-.\s]|$)")
+
+
+@dataclass
+class ScannerError(Exception):
+    kind: str
+    message: str
+    line_num: int | None = None
+    line: str | None = None
+    lines: list[int] = field(default_factory=list)
+
+    def __str__(self) -> str:
+        return f"{self.kind}: {self.message}"
+
+
+def _strip_inline_comments(line: str, opener: str, closer: str) -> str:
+    while True:
+        start = line.find(opener)
+        if start < 0:
+            return line
+        end = line.find(closer, start + len(opener))
+        if end < 0:
+            return line
+        line = line[:start] + line[end + len(closer):]
+
+
+def _comment_still_open(line: str, opener: str, closer: str) -> bool:
+    last_open = line.rfind(opener)
+    last_close = line.rfind(closer)
+    return last_open >= 0 and last_open > last_close
+
+
+def _is_release_like_heading(line: str, whitelist: list[str]) -> bool:
+    s = line.lstrip()
+    if not s.startswith("## "):
+        return False
+    rest = s[3:].strip()
+    for label in whitelist:
+        if rest.startswith(label) or rest.startswith(f"[{label}]"):
+            return False
+    has_bracket = "[" in rest and "]" in rest
+    has_bare_version = bool(_BARE_VERSION_RE.match(rest))
+    return has_bracket or has_bare_version
+
+
+def scan_changelog(text: str, *, pattern: re.Pattern[str], fence_marker: str, comment_open: str,
+                   comment_close: str, near_miss_whitelist: list[str]) -> list[dict[str, Any]]:
+    """Per §8: state-aware fence + comment scanner. Returns parsed entries.
+
+    Raises ScannerError on duplicate_version or near_miss_heading.
+    """
+    # INVARIANT 19: BOM strip + CRLF normalize.
+    text = text.lstrip("").replace("\r\n", "\n").replace("\r", "\n")
+
+    NORMAL = "NORMAL"
+    IN_FENCE = "IN_FENCE"
+    IN_COMMENT_BLOCK = "IN_COMMENT_BLOCK"
+    state = NORMAL
+
+    entries: list[dict[str, Any]] = []
+    seen: dict[str, int] = {}
+
+    for line_num, line in enumerate(text.split("\n"), start=1):
+        if state == IN_FENCE:
+            if line.lstrip().startswith(fence_marker):
+                state = NORMAL
+            continue
+        if state == IN_COMMENT_BLOCK:
+            if comment_close in line:
+                state = NORMAL
+            continue
+
+        if line.lstrip().startswith(fence_marker):
+            state = IN_FENCE
+            continue
+
+        stripped = _strip_inline_comments(line, comment_open, comment_close)
+        if _comment_still_open(stripped, comment_open, comment_close):
+            stripped = stripped[:stripped.rindex(comment_open)].rstrip()
+            state = IN_COMMENT_BLOCK
+
+        m = pattern.match(stripped)
+        if m:
+            version = m.group("version")
+            date = m.group("date")
+            if version in seen:
+                raise ScannerError(
+                    kind="changelog_duplicate_version",
+                    message=f"version {version!r} appears at lines {seen[version]} and {line_num}",
+                    lines=[seen[version], line_num],
+                )
+            seen[version] = line_num
+            entries.append({"version": version, "date": date, "line_num": line_num})
+        elif _is_release_like_heading(stripped, near_miss_whitelist):
+            raise ScannerError(
+                kind="changelog_near_miss_heading",
+                message=f"line looks like a release heading but did not match pattern: {stripped!r}",
+                line_num=line_num,
+                line=stripped,
+            )
+
+    return entries
+
+
+def scan_changelog_file(
+    path: Path,
+    *,
+    pattern: re.Pattern[str],
+    fence_marker: str,
+    comment_open: str,
+    comment_close: str,
+    near_miss_whitelist: list[str],
+) -> list[dict[str, Any]]:
+    """Read a CHANGELOG file and scan it — the shared read/decode/empty
+    failure semantics for both validators.
+
+    Raises ScannerError with kind ``changelog_decode_error`` (file is not
+    valid UTF-8) or ``changelog_empty_after_scan`` (pattern matched zero
+    entries), in addition to the scanner's own kinds.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        raise ScannerError(
+            kind="changelog_decode_error",
+            message=f"CHANGELOG is not valid UTF-8: {exc}",
+        ) from exc
+    entries = scan_changelog(
+        text,
+        pattern=pattern,
+        fence_marker=fence_marker,
+        comment_open=comment_open,
+        comment_close=comment_close,
+        near_miss_whitelist=near_miss_whitelist,
+    )
+    if not entries:
+        raise ScannerError(
+            kind="changelog_empty_after_scan",
+            message=f"changelog_entry_pattern matched zero entries in {path}",
+        )
+    return entries
+
+
+def _check_unknown_keys(data: dict[str, Any]) -> None:
+    """Raise ManifestError for any key not in the allow-list (INVARIANT 14)."""
+    for key in data:
+        if key not in _TOP_LEVEL_KEYS:
+            raise ManifestError(
+                kind="unknown_manifest_key",
+                message=f"unknown top-level key: {key}",
+                field=key,
+            )
+
+    for section_name, allowed in (("suite", _SUITE_KEYS), ("changelog", _CHANGELOG_KEYS)):
+        section = data.get(section_name)
+        if section is None:
+            continue
+        if not isinstance(section, dict):
+            raise ManifestError(
+                kind="manifest_invalid_type",
+                message=f"[{section_name}] must be a table",
+                field=section_name,
+            )
+        for key in section:
+            if key not in allowed:
+                raise ManifestError(
+                    kind="unknown_manifest_key",
+                    message=f"unknown key in [{section_name}]: {key}",
+                    field=f"{section_name}.{key}",
+                )
+
+    for kind, allowed in (("file", _FILE_KEYS), ("package", _PACKAGE_KEYS)):
+        entries = data.get(kind, [])
+        if not isinstance(entries, list):
+            raise ManifestError(
+                kind="manifest_invalid_type",
+                message=f"[[{kind}]] must be an array of tables",
+                field=kind,
+            )
+        for idx, entry in enumerate(entries):
+            if not isinstance(entry, dict):
+                raise ManifestError(
+                    kind="manifest_invalid_type",
+                    message=f"[[{kind}]] entry {idx} must be a table",
+                    field=f"{kind}[{idx}]",
+                )
+            for key in entry:
+                if key not in allowed:
+                    raise ManifestError(
+                        kind="unknown_manifest_key",
+                        message=f"unknown key in [[{kind}]] entry {idx}: {key}",
+                        field=f"{kind}[{idx}].{key}",
+                    )
+
+
+# ---------------------------------------------------------------------------
+# Package version extractors
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class PackageError(Exception):
+    """Raised when a package version cannot be extracted from a declared file.
+
+    Attributes:
+        kind: machine-readable failure code per §10 failure catalog.
+        message: human-readable explanation.
+        path: resolved file path as a string, or None if not applicable.
+    """
+
+    kind: str
+    message: str
+    path: str | None = None
+
+    def __str__(self) -> str:
+        return f"{self.kind}: {self.message}"
+
+
+def _walk_dotted(obj: Any, key: str) -> Any:
+    """Walk a dotted key path into a nested dict.
+
+    Returns the value at the terminal node, or None if any segment is
+    missing or the current node is not a dict.
+    """
+    cur = obj
+    for part in key.split("."):
+        if not isinstance(cur, dict) or part not in cur:
+            return None
+        cur = cur[part]
+    return cur
+
+
+def extract_package_version(
+    path: Path,
+    *,
+    ptype: str,
+    key: str | None,
+    pattern: str | None,
+) -> str:
+    """Extract a version string from a declared package metadata file.
+
+    Supported types:
+    - ``"toml"``: reads via tomllib, walks ``key`` (dotted notation).
+    - ``"json"``: reads via json.loads, walks ``key`` (dotted notation).
+    - ``"regex"``: compiles ``pattern`` with re.MULTILINE, requires named group
+      ``version``; exactly one match required.
+
+    Returns the extracted version string on success.
+
+    Raises:
+        PackageError(kind="package_decode_error"): file is not valid UTF-8.
+        PackageError(kind="package_version_unparseable"): key not found, not
+            a string, or zero regex matches.
+        PackageError(kind="package_version_ambiguous"): regex matched more
+            than one line (hard error per spec §10).
+        PackageError(kind="package_type_invalid"): ``ptype`` is not one of the
+            three supported values.
+
+    Precondition: when ptype in {"toml", "json"}, key must be a non-empty string;
+    when ptype == "regex", pattern must be a valid regex with named group
+    ``version``. Schema validation in load_manifest() enforces this for
+    manifest-derived calls.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        raise PackageError(
+            kind="package_decode_error",
+            message=f"package file is not valid UTF-8: {path}: {exc}",
+            path=str(path),
+        ) from exc
+
+    if ptype == "toml":
+        try:
+            data = tomllib.loads(text)
+        except tomllib.TOMLDecodeError as exc:
+            raise PackageError(
+                kind="package_version_unparseable",
+                message=f"TOML decode error in {path}: {exc}",
+                path=str(path),
+            ) from exc
+        value = _walk_dotted(data, key)
+        if not isinstance(value, str):
+            raise PackageError(
+                kind="package_version_unparseable",
+                message=f"TOML key {key!r} not found or not a string in {path}",
+                path=str(path),
+            )
+        return value
+
+    if ptype == "json":
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise PackageError(
+                kind="package_version_unparseable",
+                message=f"JSON decode error in {path}: {exc}",
+                path=str(path),
+            ) from exc
+        value = _walk_dotted(data, key)
+        if not isinstance(value, str):
+            raise PackageError(
+                kind="package_version_unparseable",
+                message=f"JSON key {key!r} not found or not a string in {path}",
+                path=str(path),
+            )
+        return value
+
+    if ptype == "regex":
+        compiled = re.compile(pattern, re.MULTILINE)
+        matches = list(compiled.finditer(text))
+        if len(matches) == 0:
+            raise PackageError(
+                kind="package_version_unparseable",
+                message=f"regex pattern matched zero lines in {path}",
+                path=str(path),
+            )
+        if len(matches) > 1:
+            raise PackageError(
+                kind="package_version_ambiguous",
+                message=(
+                    f"regex pattern matched {len(matches)} lines in {path}"
+                    " (expected exactly 1)"
+                ),
+                path=str(path),
+            )
+        # Named group presence is a precondition (validated at manifest-parse
+        # by _check_regex for manifest-derived calls).
+        return matches[0].group("version")
+
+    raise PackageError(
+        kind="package_type_invalid",
+        message=f"unknown package type: {ptype!r}",
+        path=str(path),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Version resolution (§3 + INVARIANT 22)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ResolutionResult:
+    version: str
+    date: str | None
+    source: str  # "cli_flag" | "package" | "suite_fallback"
+    warnings: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ResolutionError(Exception):
+    kind: str
+    message: str
+    detail: dict[str, Any] = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        return f"{self.kind}: {self.message}"
+
+
+def resolve_authoritative_version(
+    *,
+    manifest: dict[str, Any],
+    manifest_parent: Path,
+    expected_version: str | None,
+    ci: bool,
+) -> ResolutionResult:
+    """Per §3 + INVARIANT 22.
+
+    Order:
+      1. --expected-version wins (source=cli_flag)
+      2. [[package]] non-empty: all packages must agree (INVARIANT 22)
+      3. [suite].latest (only if --ci NOT set)
+      4. fail
+
+    Returns:
+        ResolutionResult with source in {"cli_flag", "package", "suite_fallback"}.
+
+    Raises:
+        ResolutionError with kind in {"packages_disagree",
+            "version_resolution_failed_in_ci", "version_resolution_failed"}.
+        PackageError (propagated from extract_package_version) when a declared
+            package file cannot be parsed. Can only escape when
+            expected_version is None (the CLI flag returns before any package
+            file is read), so for the caller it is always the cascade path.
+    """
+    if expected_version is not None:
+        return ResolutionResult(version=expected_version, date=None, source="cli_flag")
+
+    packages = manifest.get("package") or []
+    if packages:
+        versions: list[tuple[str, str]] = []  # (path, version)
+        for entry in packages:
+            v = extract_package_version(
+                manifest_parent / entry["path"],
+                ptype=entry["type"],
+                key=entry.get("key"),
+                pattern=entry.get("pattern"),
+            )
+            versions.append((entry["path"], v))
+
+        distinct = set(v for _, v in versions)
+        if len(distinct) > 1:
+            detail = ", ".join(f"{p}={v}" for p, v in versions)
+            raise ResolutionError(
+                kind="packages_disagree",
+                message=f"declared packages report different versions: {detail}",
+                detail={"versions": versions},
+            )
+
+        return ResolutionResult(version=versions[0][1], date=None, source="package")
+
+    suite = manifest.get("suite") or {}
+    if not ci and "latest" in suite:
+        return ResolutionResult(
+            version=suite["latest"],
+            date=suite.get("latest_date"),
+            source="suite_fallback",
+            warnings=["suite_fallback_used"],
+        )
+
+    if ci:
+        raise ResolutionError(
+            kind="version_resolution_failed_in_ci",
+            message="--ci mode requires --expected-version OR at least one [[package]] entry",
+        )
+    raise ResolutionError(
+        kind="version_resolution_failed",
+        message="no version source found: provide --expected-version, declare [[package]], or set [suite].latest",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Per-file check primitives (§7 + INVARIANT 21)
+# ---------------------------------------------------------------------------
+
+
+def _normalize(text: str) -> str:
+    """Strip leading BOM and normalise line endings to LF."""
+    return text.lstrip("").replace("\r\n", "\n").replace("\r", "\n")
+
+
+def check_release_block_presence(
+    *,
+    file_text: str,
+    entries: list[dict[str, Any]],
+    release_block_form: str,
+) -> list[dict[str, Any]]:
+    """Per INVARIANT 21: uses per-historical-entry version+date (not authoritative).
+
+    Iterates each historical CHANGELOG entry and asserts that
+    ``release_block_form`` (filled with that entry's version+date) appears in
+    ``file_text``.
+
+    Returns:
+        List of check results, one per entry, each shaped::
+
+            {"kind": "release_block_presence", "version": "<v>",
+             "expected_needle": "<rendered>", "status": "pass" | "fail"}
+    """
+    text = _normalize(file_text)
+    results: list[dict[str, Any]] = []
+    for entry in entries:
+        needle = release_block_form.replace("{version}", entry["version"]).replace(
+            "{date}", entry["date"] or ""
+        )
+        results.append({
+            "kind": "release_block_presence",
+            "version": entry["version"],
+            "expected_needle": needle,
+            "status": "pass" if needle in text else "fail",
+        })
+    return results
+
+
+def check_simple_template(
+    *,
+    file_text: str,
+    template: str,
+    authoritative_version: str,
+    authoritative_date: str | None,
+    kind: str,
+) -> dict[str, Any]:
+    """Needle check for badge_match / tag_url_match / last_updated_match.
+
+    Composes the needle from ``template`` + authoritative version/date.
+    Skips with ``reason="template_uses_date_but_date_unavailable"`` when
+    the template references ``{date}`` but ``authoritative_date`` is None.
+
+    Returns:
+        Dict shaped::
+
+            {"kind": <kind>, "status": "pass" | "fail" | "skip",
+             "expected_needle": "<rendered>"}   # absent when status=="skip"
+
+        When skipped, an additional key is present::
+
+            {"reason": "template_uses_date_but_date_unavailable"}
+    """
+    rendered = render_template(template, version=authoritative_version, date=authoritative_date)
+    if rendered is None:
+        return {
+            "kind": kind,
+            "status": "skip",
+            "reason": "template_uses_date_but_date_unavailable",
+        }
+    text = _normalize(file_text)
+    return {
+        "kind": kind,
+        "expected_needle": rendered,
+        "status": "pass" if rendered in text else "fail",
+    }