psyclaw 0.27.22 → 0.28.0

package/vendor/ars/scripts/_next_verified_at_ms.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Strict-monotonic verified_at helper for ARS v3.6.7 Step 6 (spec §5.4).
+
+Every orchestrator-side verdict.verified_at write — Path B8d normal merges,
+another_round re-merges, ship_with_known_residue acknowledgement appends —
+goes through next_verified_at_ms() so the new value is strictly greater
+than every prior persisted entry's verified_at regardless of clock
+granularity. This is what makes Path A latest-by-verified_at selection
+total-order deterministic at passport scope (§3.7 family D row D3).
+
+Reference pseudocode from spec §5.4:
+
+    def _next_verified_at_ms(passport_audit_artifacts: list) -> str:
+        now_ms = utc_now_ms()
+        if not passport_audit_artifacts:
+            return now_ms
+        latest_ms = max(entry["verdict"]["verified_at"] for entry in passport_audit_artifacts)
+        return max(now_ms, increment_ms(latest_ms, 1))
+
+`latest_ms` spans ALL prior persisted entries (not filtered by tuple) so
+total ordering holds passport-wide.
+
+Run as a CLI:
+    python scripts/_next_verified_at_ms.py --passport <path>
+        Reads passport YAML/JSON, prints the next verified_at value.
+
+Importable API:
+    from scripts._next_verified_at_ms import next_verified_at_ms
+    next_verified_at_ms(passport["audit_artifact"])  # -> "2026-...Z"
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ImportError as e:  # pragma: no cover
+    print(f"Missing dependency: {e}. Install with: pip install pyyaml", file=sys.stderr)
+    sys.exit(2)
+
+
+_RFC3339_MS_FORMAT = "%Y-%m-%dT%H:%M:%S.%f"
+
+
+def utc_now_ms() -> str:
+    """Current UTC time as RFC 3339 with millisecond precision (Z suffix)."""
+    return rfc3339_ms(datetime.now(timezone.utc))
+
+
+def parse_rfc3339_ms(s: str) -> datetime:
+    """Parse a strict RFC 3339 UTC ms-precision timestamp ('...Z' suffix).
+
+    Raises ValueError if the input does not match the exact shape
+    YYYY-MM-DDTHH:MM:SS.mmmZ — accepting other RFC 3339 variants would
+    let drift in (the schema's regex pattern enforces ms-precision).
+    """
+    if not (len(s) == 24 and s.endswith("Z") and s[-5] == "." and s[10] == "T"):
+        raise ValueError(f"not RFC 3339 ms UTC ('...Z' with .NNN): {s!r}")
+    return datetime.strptime(s[:-1] + "000", _RFC3339_MS_FORMAT).replace(tzinfo=timezone.utc)
+
+
+def rfc3339_ms(dt: datetime) -> str:
+    """Format a UTC datetime as RFC 3339 with millisecond precision."""
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    else:
+        dt = dt.astimezone(timezone.utc)
+    return dt.strftime(_RFC3339_MS_FORMAT)[:-3] + "Z"
+
+
+def bump_ms(dt: datetime, n: int = 1) -> datetime:
+    """Advance dt by n milliseconds (carries into seconds / minutes / etc.)."""
+    return dt + timedelta(milliseconds=n)
+
+
+def next_verified_at_ms(passport_audit_artifacts: list[dict[str, Any]] | None) -> str:
+    """Return the next verified_at value strictly greater than every prior entry.
+
+    Implements §5.4 pseudocode. None / [] is the empty-ledger base case
+    and returns the current UTC clock value.
+
+    Picks `latest` via lexicographic max over the prior verified_at strings.
+    For ms-precision RFC 3339 UTC strings (`YYYY-MM-DDTHH:MM:SS.NNNZ`,
+    fixed width) lex-max coincides with chronological max — this relies on
+    the schema regex (§3.2 audit_artifact_entry verified_at constraint)
+    rejecting non-canonical shapes upstream so no malformed entry can
+    sneak in and reorder the comparison.
+    """
+    now = parse_rfc3339_ms(utc_now_ms())
+    if not passport_audit_artifacts:
+        return rfc3339_ms(now)
+
+    latest_str = max(
+        entry["verdict"]["verified_at"] for entry in passport_audit_artifacts
+    )
+    latest = parse_rfc3339_ms(latest_str)
+    bumped = bump_ms(latest, 1)
+    return rfc3339_ms(max(now, bumped))
+
+
+def _load_passport_audit_artifacts(path: Path) -> list[dict[str, Any]]:
+    """Read passport YAML or JSON, return audit_artifact[] (or [] if absent).
+
+    Raises ValueError if the file cannot be parsed; CLI main() catches and
+    exits 2. The three "absent" cases (top-level not a dict, key missing,
+    value not a list) all coerce to [] for v3.6.7 — the helper is a
+    monotonic-bump primitive, not a passport validator.
+
+    TODO(Phase 6.3): scripts/check_audit_artifact_consistency.py should
+    treat `audit_artifact` present-but-not-a-list as malformed and reject,
+    not coerce silently. Lifecycle ownership rule §3.7 E2.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as e:
+        raise ValueError(f"failed to read {path}: {e}") from e
+
+    suffix = path.suffix.lower()
+    try:
+        if suffix == ".json":
+            data = json.loads(text)
+        else:
+            # Use BaseLoader so PyYAML returns every scalar as str — without
+            # this, unquoted RFC 3339 timestamps in spec-example passports
+            # (e.g. `verified_at: 2026-04-30T15:23:11.847Z`) get auto-cast
+            # to datetime objects, which would break parse_rfc3339_ms()
+            # downstream. The schema constrains verified_at to a string;
+            # strict string load matches that contract.
+            data = yaml.load(text, Loader=yaml.BaseLoader)  # noqa: S506 - intentional, str-only
+    except (yaml.YAMLError, json.JSONDecodeError) as e:
+        raise ValueError(f"failed to parse {path}: {e}") from e
+
+    if not isinstance(data, dict):
+        return []
+    artifacts = data.get("audit_artifact") or []
+    if not isinstance(artifacts, list):
+        return []
+    return artifacts
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Print the next verified_at value (RFC 3339 UTC ms) strictly "
+            "greater than every prior audit_artifact[] entry's verified_at "
+            "in the given Material Passport (§5.4)."
+        ),
+    )
+    parser.add_argument(
+        "--passport",
+        required=True,
+        type=Path,
+        help="Path to passport YAML or JSON containing audit_artifact[].",
+    )
+    args = parser.parse_args(argv)
+
+    if not args.passport.exists():
+        print(f"ERROR: passport not found: {args.passport}", file=sys.stderr)
+        return 2
+
+    try:
+        artifacts = _load_passport_audit_artifacts(args.passport)
+    except ValueError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 2
+    print(next_verified_at_ms(artifacts))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/vendor/ars/scripts/_passport_yaml.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Shared ruamel.yaml round-trip configuration for passport migration tools.
+
+For tools that **mutate and re-emit** passport YAML (preserving comments,
+key order, quoting). Read-only validators should keep using `yaml.safe_load`.
+
+Previously duplicated byte-equivalently in
+`migrate_literature_corpus_to_v3_7_3.py` and
+`migrate_literature_corpus_to_v3_9_0.py`. Extracted in #128 (v3.9.1
+housekeeping) so future migration tools inherit the spec-aligned round-trip
+shape without re-deriving it.
+
+Behavior must remain byte-equivalent with the per-tool configuration that
+was verified across multiple v3.7.3 / v3.9.0 review rounds. See
+`test_passport_yaml.py` for the configuration + round-trip contract.
+
+Configuration:
+- preserve_quotes = True → keeps single vs double quoting choice.
+- indent(mapping=2, sequence=4, offset=2) → sequence items align with `- `
+  two spaces past the parent key, matching the passport convention used
+  by `shared/contracts/passport/literature_corpus_entry.schema.json` examples.
+
+Thread-safety: single-threaded use only. The module-level `_yaml` is a shared
+mutable singleton; instantiate per-thread (or per-call) if future tools
+parallelize passport migration.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ruamel.yaml import YAML
+
+
+# Single shared YAML round-tripper. ruamel.yaml preserves comments,
+# key order, and quoting style across read → mutate → write.
+_yaml = YAML()
+_yaml.preserve_quotes = True
+_yaml.indent(mapping=2, sequence=4, offset=2)
+
+
+def load_passport(path: Path) -> Any:
+    """Round-trip load a passport YAML file. Returns the ruamel-yaml
+    representation (a CommentedMap), not a plain dict."""
+    with path.open("r", encoding="utf-8") as f:
+        return _yaml.load(f)
+
+
+def dump_passport(path: Path, doc: Any) -> None:
+    """Round-trip dump a passport YAML document back to disk, preserving
+    comments / key order / quoting style from the matching load."""
+    with path.open("w", encoding="utf-8") as f:
+        _yaml.dump(doc, f)

package/vendor/ars/scripts/_skill_lint.py

@@ -0,0 +1,254 @@
+"""Shared helpers for SKILL.md frontmatter linting + cross-lint H2-section
+literal checks.
+
+Frontmatter helpers (check_data_access_level.py, check_task_type.py)
+validate that every top-level SKILL.md declares a required metadata field
+drawn from a closed vocabulary.
+
+`h2_section_body` / `check_section_literals` are the H2 line-walk variant
+shared by the block-scoped string-check lints (check_394, check_390): the
+"named H2 must exist and carry every load-bearing literal" pattern. This is
+ONE of several section extractors in scripts/ — the heading-level / regex /
+fence-aware variants (check_392, check_216, check_firm_rules_sync) are
+deliberately not interchangeable with this plain line-walk and are not
+consolidated here.
+
+`norm_ws` / `read_or_exit2` are the verbatim-witness-lint pair
+(check_reviewer_data_fences, check_reviewer_finding_contract): whitespace
+folding is load-bearing for "verbatim match modulo wrapping" pins, so it must
+be single-sourced rather than re-implemented per lint. (Older lints with
+private `_norm` copies — check_instruction_data_boundary,
+check_firm_rules_sync — predate this helper; migrating them is a follow-up.)
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+SKIP_DIRS = frozenset(
+    {"shared", "scripts", "docs", ".git", ".github", "examples", ".local-plans", ".claude"}
+)
+
+
+class FrontmatterError(Exception):
+    """Raised when SKILL.md frontmatter cannot be parsed.
+
+    Distinct from a missing fence (returns None) and an empty fence
+    (returns {}). Callers should catch this and surface the path +
+    parser detail on stdout, not stderr — CI logs commonly capture
+    only stdout.
+    """
+
+
+def iter_skill_files(root: Path) -> list[Path]:
+    """Top-level SKILL.md files only. Skips SKIP_DIRS."""
+    results: list[Path] = []
+    for child in sorted(root.iterdir()):
+        if not child.is_dir() or child.name in SKIP_DIRS:
+            continue
+        skill_md = child / "SKILL.md"
+        if skill_md.is_file():
+            results.append(skill_md)
+    return results
+
+
+def parse_frontmatter(path: Path) -> dict | None:
+    """Parse the YAML frontmatter of a SKILL.md.
+
+    Three outcomes:
+      - dict (possibly empty) — fence present and parseable
+      - None                  — no opening '---' fence
+      - raises FrontmatterError — fence present but YAML invalid
+    """
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return None
+    match = re.match(r"\A---\r?\n(?P<fm>.*?)(?:\r?\n)---(?:\r?\n|$)", text, re.DOTALL)
+    if not match:
+        raise FrontmatterError(f"{path}: missing closing YAML frontmatter fence")
+    fm = match.group("fm")
+    try:
+        data = yaml.safe_load(fm) or {}
+    except yaml.YAMLError as exc:
+        raise FrontmatterError(f"{path}: malformed YAML frontmatter: {exc}") from exc
+    if not isinstance(data, dict):
+        raise FrontmatterError(
+            f"{path}: YAML frontmatter must be a mapping/object, got {type(data).__name__}"
+        )
+    return data
+
+
+def split_frontmatter(text: str) -> tuple[dict | None, str]:
+    """Split YAML frontmatter from body. Lenient variant of parse_frontmatter.
+
+    Unlike parse_frontmatter, callers here need access to the body and
+    prefer "no frontmatter" to an exception when YAML is malformed (the
+    caller's surrounding check will surface the structural error). Both
+    invalid-fence and invalid-YAML return (None, text) rather than raising.
+    """
+    if not text.startswith("---"):
+        return None, text
+    match = re.match(r"\A---\r?\n(?P<fm>.*?)(?:\r?\n)---(?:\r?\n|$)", text, re.DOTALL)
+    if not match:
+        return None, text
+    try:
+        data = yaml.safe_load(match.group("fm")) or {}
+    except yaml.YAMLError:
+        return None, text
+    if not isinstance(data, dict):
+        return None, text
+    return data, text[match.end():]
+
+
+def check_metadata_field(
+    root: Path,
+    field: str,
+    legal_values: set[str] | frozenset[str],
+) -> list[str]:
+    """Return a list of human-readable violation messages, empty if all pass."""
+    violations: list[str] = []
+    skills = iter_skill_files(root)
+    if not skills:
+        violations.append(f"no SKILL.md files found under {root}")
+        return violations
+    for path in skills:
+        try:
+            fm = parse_frontmatter(path)
+        except FrontmatterError as exc:
+            violations.append(str(exc))
+            continue
+        if fm is None:
+            violations.append(f"{path}: missing YAML frontmatter")
+            continue
+        metadata = fm.get("metadata") or {}
+        if field not in metadata:
+            violations.append(f"{path}: metadata.{field} is missing")
+            continue
+        value = metadata[field]
+        if value not in legal_values:
+            violations.append(
+                f"{path}: metadata.{field} = {value!r}, "
+                f"must be one of {sorted(legal_values)}"
+            )
+    return violations
+
+
+def h2_section_body(text: str, heading: str) -> str | None:
+    """Return the BODY of the H2 starting with `heading` (heading line
+    excluded) up to the next H2, or None when the heading is absent. The
+    section boundary is explicit: a line is a boundary iff it starts a new
+    H2 (`## `); internal H3s and code fences are part of the body."""
+    body: list[str] = []
+    in_section = False
+    for line in text.splitlines():
+        if line.startswith(heading):
+            in_section = True
+            continue
+        if in_section and line.startswith("## "):
+            break
+        if in_section:
+            body.append(line)
+    return "\n".join(body) if in_section else None
+
+
+def check_section_literals(invariant: int, text: str, heading: str,
+                           label: str,
+                           literals: dict[str, str]) -> list[str]:
+    """The named H2 section must exist and carry every load-bearing literal.
+    Shared by the block-scoped string-check lints (check_394, check_390)."""
+    section = h2_section_body(text, heading)
+    if section is None:
+        return [f"invariant {invariant}: {label} section '{heading}' missing"]
+    return [
+        f"invariant {invariant}: {label} section lost the "
+        f"{name} literal ({literal!r})"
+        for name, literal in literals.items()
+        if literal not in section
+    ]
+
+
+def heading_section(text: str, heading: str) -> str | None:
+    """Return the body of the section opened by the exact heading line
+    (column 0, outside ``` fences), up to the next heading of the SAME or
+    HIGHER level outside fences — deeper child headings stay inside the body.
+    None if absent. Nestable: pass a parent section's body back in to bind a
+    child heading to that parent (delivery-block scoping — a heading matched
+    anywhere in the file is NOT the delivered block)."""
+    open_level = len(heading) - len(heading.lstrip("#"))
+    stop = re.compile(rf"#{{1,{open_level}}} ")
+    # Both Markdown fence forms count — a heading "hidden" in a ~~~ block must
+    # not read as a real section boundary (CommonMark close: same fence char,
+    # run length >= the opening run, at most 3 spaces of indentation).
+    fence_re = re.compile(r"[ ]{0,3}(`{3,}|~{3,})")
+    # A CLOSING fence is the run alone on its line (CommonMark: no info string
+    # on a closer — "~~~not-a-close" does NOT close a ~~~ block — and a
+    # 4-space-indented run is content, not a closer).
+    fence_close_re = re.compile(r"[ ]{0,3}(`{3,}|~{3,})\s*$")
+    fence: str | None = None  # the opening fence run while inside a fenced block
+    started = False
+    body: list[str] = []
+    for line in text.splitlines(keepends=True):
+        m = fence_re.match(line)
+        if fence is not None:
+            mc = fence_close_re.match(line)
+            if mc and mc.group(1)[0] == fence[0] and len(mc.group(1)) >= len(fence):
+                fence = None
+            if started:
+                body.append(line)
+            continue
+        if m:
+            fence = m.group(1)
+            if started:
+                body.append(line)
+            continue
+        if not started:
+            if line.rstrip("\n") == heading:
+                started = True
+            continue
+        if stop.match(line):
+            break
+        body.append(line)
+    return "".join(body) if started else None
+
+
+def norm_ws(text: str) -> str:
+    """Collapse all whitespace runs so line-wrapping does not defeat a
+    verbatim-witness compare. Load-bearing for the fence/finding-contract
+    pins — hardening added here reaches every importing lint at once."""
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def read_or_exit2(root: Path, rel: str) -> str:
+    """Read a required lint surface; a missing file is an invocation error
+    (exit 2), never a lint failure (exit 1)."""
+    p = root / rel
+    if not p.is_file():
+        print(f"ERROR: required file missing: {rel}", file=sys.stderr)
+        raise SystemExit(2)
+    return p.read_text(encoding="utf-8")
+
+
+def run_lint(field: str, legal_values: set[str] | frozenset[str], ok_message: str) -> int:
+    """argparse + check + print + exit-code wrapper (check_task_type.py;
+    check_data_access_level.py grew its own #756 pin-layer main and no
+    longer uses this)."""
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--path",
+        type=Path,
+        default=Path(__file__).resolve().parent.parent,
+    )
+    args = parser.parse_args()
+
+    violations = check_metadata_field(args.path, field, legal_values)
+    if violations:
+        for v in violations:
+            print(f"ERROR: {v}")
+        print(f"\n{len(violations)} violation(s) found.", file=sys.stderr)
+        return 1
+    print(ok_message)
+    return 0

package/vendor/ars/scripts/_text_similarity.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Shared title-similarity + retry-budget helpers for the v3.9.0 cross-index
+triangulation clients.
+
+Previously triple-implemented byte-equivalently in
+`semantic_scholar_client.py`, `openalex_client.py`, and `crossref_client.py`.
+Extracted in #128 (v3.9.1 housekeeping) to prevent sibling drift — any
+threshold tuning or normalization rule change now happens in one place.
+
+`_normalize_title` / `_similarity` stay byte-equivalent with the v3.7.3 /
+v3.9.0 client implementations for every NON-dotted-acronym title; #431 §0.1
+adds a dotted-acronym pre-pass that can only *raise* `_similarity` (taken via
+`max`), plus the `exact_normalized_title` / `generic_title` identity helpers the
+exact-title-or-bust gate (§0.12) reads. See `test_text_similarity.py` for the
+similarity contract and `test_431_exact_or_bust.py` for the gate behavior.
+"""
+from __future__ import annotations
+
+import re
+import string
+from difflib import SequenceMatcher
+
+
+_PUNCT_TRANSLATION = str.maketrans({c: " " for c in string.punctuation})
+
+# #431 §0.1: collapse a run of two-or-more `<letter>.` units at a word boundary
+# (`R.A.G.` → `RAG`) BEFORE punctuation→whitespace, so a dotted acronym and its
+# undotted spelling normalize byte-equal. `/`, `&`, and spaced initials
+# (`D. H.`) are NOT dotted runs and stay untouched (`A/B`, `R&D`, `Q&A`).
+_DOTTED_ACRONYM = re.compile(r"\b(?:[A-Za-z]\.){2,}")
+
+
+# Per protocol: shared retry budget for the index clients. S2 / Crossref
+# sleep a fixed _BACKOFF_SECONDS per 429; OpenAlex uses it as the base of
+# an exponential backoff (2s → 4s → 8s, #495); arXiv does not use it — its
+# 429 backoff is the 3s ToU pacing floor (_ARXIV_MIN_INTERVAL, #495).
+_BACKOFF_SECONDS = 2.0
+_MAX_RETRIES = 3
+
+
+# Per PaperOrchestra (Song et al. 2026 Appx D.3) + protocol §"Query Patterns"
+# Pattern 1: title-similarity threshold for "matched" verdict.
+_TITLE_SIMILARITY_THRESHOLD = 0.70
+
+
+def _normalize_title(s: str) -> str:
+    """Per protocol §"Query Patterns" Pattern 1: 'case-insensitive, stripped
+    of punctuation' before computing similarity. Punctuation becomes
+    whitespace so token boundaries are preserved, then collapse runs of
+    whitespace. The byte-equivalent base form for every non-dotted title."""
+    cleaned = s.lower().translate(_PUNCT_TRANSLATION)
+    return " ".join(cleaned.split())
+
+
+def _normalize_title_acronym(s: str) -> str:
+    """#431 §0.1: base normalization plus the dotted-acronym pre-pass. The
+    dots inside a `<letter>.`-run span are stripped first (`R.A.G.` → `RAG`),
+    then the base path runs. Provably additive over the dotted form only — any
+    title with no dotted run normalizes identically to `_normalize_title`.
+
+    This is the form `exact_normalized_title` compares on: under #431's
+    exact-title-or-bust gate the equality (not the ratio) is load-bearing, so a
+    legitimate `R.A.G.`/`RAG` acronym variant must reach byte-equality here. The
+    base form alone leaves them 'r a g …' ≠ 'rag …' — a high ratio but NOT
+    equal, which under the gate would wrongly fall to `unresolvable`."""
+    collapsed = _DOTTED_ACRONYM.sub(lambda m: m.group(0).replace(".", ""), s)
+    return _normalize_title(collapsed)
+
+
+def _similarity(a: str, b: str) -> float:
+    """`max` over the base and dotted-acronym normalizations (#431 §0.1,
+    F4 non-destructive): the acronym pre-pass can only ever *raise* the score,
+    so `D. H.` vs `D. H.` stays 1.000 (it would be 0.981 if the acronym form
+    replaced the base form). For non-dotted titles both forms are byte-equal, so
+    the second pass is skipped and the result is the pre-#431 single-form ratio."""
+    a_base, b_base = _normalize_title(a), _normalize_title(b)
+    base = SequenceMatcher(None, a_base, b_base).ratio()
+    a_acr, b_acr = _normalize_title_acronym(a), _normalize_title_acronym(b)
+    if a_acr == a_base and b_acr == b_base:  # no dotted run in either title
+        return base
+    return max(base, SequenceMatcher(None, a_acr, b_acr).ratio())
+
+
+def exact_normalized_title(a: str, b: str) -> bool:
+    """#431 §0.12.1: the one identity signal all four resolvers can compute.
+    True iff the two titles are byte-equal under EITHER the base normalization
+    OR the dotted-acronym-aware one. Both forms are checked (mirroring
+    `_similarity`'s `max`, F4 non-destructive): the acronym pre-pass must only
+    ever *add* matches, never drop one the base form already had. Checking only
+    the acronym form would regress a punctuation-only variant where exactly one
+    side is a contiguous initialism — `D.H. Lawrence` vs `D. H. Lawrence`
+    normalizes byte-equal under the base form (`d h lawrence`) but NOT under the
+    acronym form (`dh` vs `d h`), and would wrongly fall to `unresolvable`.
+    Legitimate punctuation / case / subtitle-spacing / `R.A.G.`→`RAG` acronym
+    variants all match here; a distinct related work (different subtitle, Part I
+    vs Part II, a correction-notice prefix) matches under neither and stays
+    `unresolvable` rather than a false `matched`."""
+    return (
+        _normalize_title(a) == _normalize_title(b)
+        or _normalize_title_acronym(a) == _normalize_title_acronym(b)
+    )
+
+
+# #431 §0.12.2: the closed generic/section/type/notice set. `generic_title` is
+# EXACT set-membership on the normalized title — NOT substring or endswith. A
+# content title that merely begins with or contains a type word (`Case Report of
+# a Rare Tumor`, `A Comprehensive Review`) has a normalized form ≠ the bare type
+# word, so it is NOT generic and is not demoted. This list is the single source
+# of truth (spec §0.12.2); the regression fixture pins `Short Communication` /
+# `Editorial Comment` / `Case Report` / `Publisher Correction` (exact title + no
+# ID) → `unresolvable`.
+_GENERIC_TITLES = frozenset(
+    _normalize_title(t)
+    for t in (
+        "editorial", "guest editorial", "editorial comment", "introduction",
+        "preface", "foreword", "letter", "letters", "letter to the editor",
+        "letters to the editor", "reply", "comment", "commentary", "response",
+        "correspondence", "book review", "book reviews", "review", "news",
+        "obituary", "in memoriam", "acknowledgements", "front matter",
+        "back matter", "table of contents", "abstracts", "abstract",
+        "proceedings", "keynote", "panel discussion", "workshop summary",
+        "special issue", "untitled", "note", "notes", "highlights", "errata",
+        "erratum", "corrigendum", "addendum", "author correction",
+        "publisher correction", "retraction", "expression of concern",
+        "short communication", "rapid communication", "brief communication",
+        "short report", "brief report", "technical report", "meeting report",
+        "conference report", "case report", "case study", "research article",
+        "original article", "original research", "short paper", "perspective",
+        "perspectives", "viewpoint", "opinion", "discussion", "summary",
+        "conclusion", "conclusions", "abstract only", "supplementary material",
+    )
+)
+
+
+def generic_title(title: str) -> bool:
+    """#431 §0.12.2: True iff the normalized title is byte-equal to a member of
+    the closed generic set. Under the exact-or-bust gate an exact title match
+    that is *also* generic accepts only when an ID/DOI corroborates; otherwise
+    it is `unresolvable` (a bare `Editorial` collides across thousands of
+    distinct works)."""
+    return _normalize_title(title) in _GENERIC_TITLES