suppression_governance_selftest.py

Go to the documentation of this file.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Brighton Sikarskie
"""Both-direction fixtures for typed repository-governance controls."""
 
from __future__ import annotations
 
import ast
from pathlib import Path
 
from selftest_assert import expect
from suppression_checker_census import (
    census_bindings,
    mutation_findings,
    shape_problem,
    sink_findings,
)
from suppression_checker_nonfatal import _active_usages, _option_declarations
from suppression_checker_scope import (
    PolicyValue,
    ResolvedAuthority,
    _authority_value_digest,
    _collect_authorities,
    _condition_dependent,
    _resolve,
    _resolve_registered,
    _scan_scope_file,
)
from suppression_generated_markers import effective_head_waiver, generated_records
from suppression_governance import (
    GLOBAL_EXCLUSION_AUTHORITIES,
    scan_ansible_lint_config,
    scan_ci_parity_exemptions,
    scan_doxygen_controls,
    scan_gitignore_exemptions,
    scan_other_language_controls,
    scan_registered_global_exclusions,
    scan_security_controls,
)
from suppression_hardware_todo import scan_hardware_todo_controls
from suppression_hash_lex import hash_lines
from suppression_scope_registry import AUTHORITY_SCHEMAS, AuthoritySchema
 
EXPECTED_ANSIBLE_FIXTURE_ROWS = 3
EXPECTED_DOXYGEN_FIXTURE_ROWS = 7
EXPECTED_SECURITY_FIXTURE_ROWS = 3
EXPECTED_NONFATAL_FIXTURE_ROWS = 9
EXPECTED_UNCLASSIFIED_FIXTURES = 2
 
 
def _assert_generated_body(root: Path, generator: str, canonical: str, failures: list[str]) -> None:
    """Assert generated provenance requires real generated content."""
    record, findings = generated_records(
        "generated.py", canonical, frozenset({"generated.py", generator}), root
    )
    expect(
        len(record) == 1 and not findings,
        "must fire: canonical generated marker has provenance and a real body",
        failures,
    )
    for body in (
        "",
        "\n\n",
        "# comment only\n",
        "/* comment only */\n",
        "/* unterminated comment only\n",
    ):
        marker_only = "# @generated by tools/generator.py -- fixture recipe\n" + body
        record, problems = generated_records(
            "generated.py", marker_only, frozenset({"generated.py", generator}), root
        )
        expect(
            not record and any(item.code == "generated-marker-without-body" for item in problems),
            "must fire: marker-only, blank-only, and comment-only artifacts do not waive",
            failures,
        )
    for text in (
        'value = "@generated by tools/generator.py -- string prose"\n',
        "\n" * 40 + canonical,
    ):
        waiver, problems = effective_head_waiver(text, tracked_paths=frozenset({generator}))
        expect(
            waiver is None and not problems,
            "quiet: prose and deep generated hints do not waive",
            failures,
        )
 
 
def _assert_generated_syntax(generator: str, failures: list[str]) -> None:
    """Assert malformed and punctuation-only marker syntax fails closed."""
    for malformed in (
        "# @generated\n",
        "# @generated by\n",
        "# FILE-SIZE-OK\n",
        "# FILE-SIZE-OK:\n",
    ):
        waiver, problems = effective_head_waiver(malformed)
        expect(
            waiver is None and any(item.code == "malformed-generated-marker" for item in problems),
            "must fire: bare and malformed generated/file-size markers are inventoried",
            failures,
        )
    for punctuation in ("-", "--", ":", "()"):
        text = f"# @generated by tools/generator.py {punctuation}\nVALUE = 1\n"
        waiver, problems = effective_head_waiver(text, tracked_paths=frozenset({generator}))
        expect(
            waiver is None
            and any(item.code == "non-substantive-waiver-reason" for item in problems),
            "must fire: delimiter-only generated rationales cannot waive",
            failures,
        )
    waiver, problems = effective_head_waiver("# FILE-SIZE-OK: -\nVALUE = 1\n")
    expect(
        waiver is None and any(item.code == "non-substantive-waiver-reason" for item in problems),
        "must fire: delimiter-only FILE-SIZE-OK rationale cannot waive",
        failures,
    )
 
 
def _assert_generated_provenance(root: Path, canonical: str, failures: list[str]) -> None:
    """Assert generator identity is tracked, real, and distinct from output."""
    self_marker = "# @generated by tools/generated.py -- deterministic self fixture\nVALUE = 1\n"
    record, problems = generated_records(
        "tools/generated.py", self_marker, frozenset({"tools/generated.py"}), root
    )
    expect(
        not record and any(item.code == "self-generated-provenance" for item in problems),
        "must fire: a generated artifact cannot name itself as its generator",
        failures,
    )
    missing_marker = (
        "# @generated by tools/missing.py -- deterministic missing fixture\nVALUE = 1\n"
    )
    record, problems = generated_records(
        "generated.py",
        missing_marker,
        frozenset({"generated.py", "tools/missing.py"}),
        root,
    )
    expect(
        not record and any(item.code == "missing-generated-provenance" for item in problems),
        "must fire: tracked text cannot impersonate a missing generator file",
        failures,
    )
    _waiver, problems = effective_head_waiver(canonical, tracked_paths=frozenset({"generated.py"}))
    expect(
        any(item.code == "untracked-generated-provenance" for item in problems),
        "must fire: generated provenance must resolve to a tracked path",
        failures,
    )
    _assert_generator_identity(root, failures)
 
 
def _assert_generator_identity(root: Path, failures: list[str]) -> None:
    """Assert generator identity rejects symlink, hard-link, and nonregular routes."""
    artifact = root / "generated.py"
    artifact.write_text(
        "# @generated by tools/alias.py -- symlink loop fixture\nVALUE = 1\n",
        encoding="ascii",
    )
    (root / "tools" / "alias.py").symlink_to(artifact)
    tracked = frozenset({"generated.py", "tools/alias.py", "tools/linked.py", "tools/dir.py"})
    record, problems = generated_records("generated.py", artifact.read_text(), tracked, root)
    expect(
        not record and any(item.code == "symlinked-generated-provenance" for item in problems),
        "must fire: a symlink generator cannot launder self-provenance",
        failures,
    )
    escape = root / "tools" / "escape.py"
    escape.symlink_to(root.parent / "outside-generator.py")
    text = "# @generated by tools/escape.py -- escaping symlink fixture\nVALUE = 1\n"
    record, problems = generated_records(
        "generated.py", text, tracked | frozenset({"tools/escape.py"}), root
    )
    expect(
        not record and any(item.code == "symlinked-generated-provenance" for item in problems),
        "must fire: a symlink pointing outside the repository cannot waive",
        failures,
    )
    (root / "tools" / "linked.py").hardlink_to(artifact)
    text = "# @generated by tools/linked.py -- hard-link loop fixture\nVALUE = 1\n"
    artifact.write_text(text, encoding="ascii")
    record, problems = generated_records("generated.py", text, tracked, root)
    expect(
        not record and any(item.code == "self-generated-provenance" for item in problems),
        "must fire: a hard-linked generator shares the artifact's file identity",
        failures,
    )
    (root / "tools" / "dir.py").mkdir()
    text = "# @generated by tools/dir.py -- nonregular generator fixture\nVALUE = 1\n"
    record, problems = generated_records("generated.py", text, tracked, root)
    expect(
        not record and any(item.code == "missing-generated-provenance" for item in problems),
        "must fire: a directory is not a regular generator file",
        failures,
    )
    text = "# @generated by tools/generator.py -- distinct real generator fixture\nVALUE = 1\n"
    artifact.write_text(text, encoding="ascii")
    record, problems = generated_records(
        "generated.py", text, frozenset({"generated.py", "tools/generator.py"}), root
    )
    expect(
        len(record) == 1 and not problems,
        "quiet: a distinct regular tracked generator still waives",
        failures,
    )
    artifact.unlink()
 
 
def _assert_generated(root: Path, failures: list[str]) -> None:
    """Run every generated-marker grammar and provenance assertion."""
    generator = "tools/generator.py"
    (root / "tools").mkdir(exist_ok=True)
    (root / generator).write_text("# fixture generator\n", encoding="ascii")
    canonical = "# @generated by tools/generator.py -- deterministic fixture recipe\nVALUE = 1\n"
    _assert_generated_body(root, generator, canonical, failures)
    _assert_generated_syntax(generator, failures)
    _assert_generated_provenance(root, canonical, failures)
 
 
def _assert_config_parsers(failures: list[str]) -> None:
    """Assert structured Ansible/Doxygen authorities and prose controls."""
    ansible = """---
skip_list:
  - name[template]  # role is generated from a pinned template
warn_list:
  - experimental  # advisory rollout
exclude_paths:
  - fixtures/  # upstream syntax fixtures
"""
    rows, findings = scan_ansible_lint_config(".ansible-lint", ansible)
    expect(
        len(rows) == EXPECTED_ANSIBLE_FIXTURE_ROWS
        and not findings
        and all(not item.concerns for item in rows),
        "must fire: typed ansible-lint list items carry item reasons",
        failures,
    )
    rows, _findings = scan_ansible_lint_config("docs/readme.txt", "ansible-lint skip_list is prose")
    expect(not rows, "quiet: ansible-lint prose is not configuration", failures)
    expect(
        not GLOBAL_EXCLUSION_AUTHORITIES
        and not scan_registered_global_exclusions("pyproject.toml", "exclude_files = ['fixture']")[
            0
        ],
        "quiet: no generic non-Ruff exclusion substring becomes an authority",
        failures,
    )
    doxy = """# Shared warning policy.
WARN_IF_UNDOCUMENTED = NO
WARN_NO_PARAMDOC = NO
WARN_AS_ERROR = NO
# Exclude generated and vendor inputs.
EXCLUDE = vendor \\
          generated
EXCLUDE_PATTERNS += */build/* \\
                    */tests/*
"""
    rows, findings = scan_doxygen_controls("Doxyfile", doxy)
    expect(
        len(rows) == EXPECTED_DOXYGEN_FIXTURE_ROWS and not findings,
        "must fire: Doxyfile scalar, multiline, and += assignments split per value",
        failures,
    )
    rows, _findings = scan_doxygen_controls("vendor/Doxyfile", doxy)
    expect(not rows, "quiet: only the repository-root Doxyfile is authoritative", failures)
 
 
def _assert_bound_markers(root: Path, failures: list[str]) -> None:
    """Assert gitignore and CI markers bind to their exact consumers."""
    text = "# gitignore-scope-ok: producer writes relative to cwd\ndownloads/\n"
    rows, findings = scan_gitignore_exemptions(".gitignore", text)
    expect(
        len(rows) == 1 and rows[0].scope == "pattern:downloads/" and not findings,
        "must fire: gitignore marker binds one unanchored directory pattern",
        failures,
    )
    rows, findings = scan_gitignore_exemptions(".gitignore", "# gitignore-scope-ok:\ndownloads/\n")
    expect(
        not rows and bool(findings),
        "must fire: blank gitignore marker reason cannot waive",
        failures,
    )
    workflow = root / ".github" / "workflows" / "fixture.yml"
    workflow.parent.mkdir(parents=True, exist_ok=True)
    workflow.write_text(
        """name: fixture
on: [push]
jobs:
  fixture:
    runs-on: ubuntu-latest
    steps:
      - name: Provision fixture runner
        run: |
          # ci-parity: infra -- installs fixture runner packages only
          true
""",
        encoding="ascii",
    )
    rows, findings = scan_ci_parity_exemptions(root, [".github/workflows/fixture.yml"])
    expect(
        len(rows) == 1
        and rows[0].scope == "job:fixture/step:Provision fixture runner"
        and not findings,
        "must fire: CI infra marker binds workflow/job/step identity",
        failures,
    )
 
 
def _assert_language_controls(failures: list[str]) -> None:
    """Assert exact security/other-language syntax and ownership boundaries."""
    security = """# nosemgrep:python.lang.security.audit -- generated command is fixed
# NOSONAR -- compatibility fixture is intentionally analyzer-neutral
# lgtm[py/path-injection] -- legacy query evidence remains reviewable
value = "NOSONAR"
"""
    rows, findings = scan_security_controls("scripts/checks/check_suppressions.py", security)
    expect(
        len(rows) == EXPECTED_SECURITY_FIXTURE_ROWS
        and {item.tool for item in rows} == {"semgrep", "sonarqube", "codeql-legacy"}
        and not findings,
        "must fire: exact first-party Semgrep, Sonar, and legacy LGTM comments",
        failures,
    )
    rows, _findings = scan_security_controls("libs/third_party/vendor/fixture.py", security)
    expect(not rows, "quiet: vendor security evidence is not first-party debt", failures)
    fixtures = {
        "tools/fixture.java": (
            '@SuppressWarnings("unchecked") // generated bridge has a checked boundary\n',
            "java",
        ),
        "tools/fixture.kt": (
            '@Suppress("UNCHECKED_CAST") // generated bridge has a checked boundary\n',
            "kotlin",
        ),
        "tools/fixture.rs": (
            "#[expect(clippy::cast_possible_truncation)] // bounded fixture conversion\n",
            "rust",
        ),
        "tools/fixture.go": (
            "//nolint:gosec // generated fixture uses a fixed command\n",
            "go",
        ),
    }
    for path, (text, tool) in fixtures.items():
        rows, findings = scan_other_language_controls(path, text)
        expect(
            len(rows) == 1 and rows[0].tool == tool and not findings,
            f"must fire: exact {tool} suppression syntax in a matching file",
            failures,
        )
    rust = fixtures["tools/fixture.rs"][0]
    rows, _findings = scan_other_language_controls("tools/fixture.py", rust)
    expect(not rows, "quiet: other-language syntax in the wrong extension is data", failures)
 
 
def _assert_cmake_bracket_lexing(failures: list[str]) -> None:
    """Assert balanced bracket comments mask directives and EOF fails closed."""
    text = """#[=[
# nosemgrep:fixture.hidden -- bracket-comment payload
]=]
# nosemgrep:fixture.live -- ordinary CMake comment
"""
    lines, findings = hash_lines("CMakeLists.txt", text)
    comments = [(item.line, item.comment.strip()) for item in lines if item.comment]
    expect(
        comments == [(4, "nosemgrep:fixture.live -- ordinary CMake comment")] and not findings,
        "quiet: balanced CMake bracket-comment payload is masked while outside fires",
        failures,
    )
    lines, findings = hash_lines("fixture.cmake", "#[[ nosemgrep:fixture.hidden ]]\n")
    expect(
        all(not item.comment for item in lines) and not findings,
        "quiet: simple CMake bracket comments are masked too",
        failures,
    )
    _lines, findings = hash_lines("fixture.cmake", "#[[ unterminated\n")
    expect(
        any(item.code == "unterminated-cmake-bracket" for item in findings),
        "must fire: unterminated CMake bracket comment fails closed",
        failures,
    )
 
 
def _assert_hardware_binding(root: Path, failures: list[str]) -> None:
    """Assert only named-hardware CANNED candidates bind, never SHADOW."""
    app = root / "apps" / "fixture"
    app.mkdir(parents=True, exist_ok=True)
    waived = app / "waived.c"
    waived.write_text(
        """/* TODO(fixture radio module is not installed) */
int fixture_radio(int value) { (void)value; return k_ra8_err_not_supported; }
""",
        encoding="ascii",
    )
    generic = app / "generic.c"
    generic.write_text(
        """/* TODO: later */
int fixture_generic(int value) { (void)value; return k_ra8_err_not_supported; }
""",
        encoding="ascii",
    )
    rows, findings = scan_hardware_todo_controls(
        root, ["apps/fixture/waived.c", "apps/fixture/generic.c"]
    )
    expect(
        len(rows) == 1 and rows[0].scope == "function:fixture_radio" and not findings,
        "must fire: named hardware TODO binds one canned stub; generic TODO stays quiet",
        failures,
    )
    real = app / "real.c"
    real.write_text("int fixture_radio(int value) { return value + 1; }\n", encoding="ascii")
    rows, _findings = scan_hardware_todo_controls(
        root, ["apps/fixture/waived.c", "apps/fixture/real.c"]
    )
    expect(not rows, "quiet: SHADOW candidates are never hardware-waivable", failures)
 
 
def _assert_scope_value_semantics(failures: list[str]) -> None:
    """Assert explicit AST schemas preserve values, reasons, and identity digests."""
    expr = ast.parse("VALUE = ('path with spaces/', 'two/')\n").body[0]
    expect(isinstance(expr, ast.Assign), "fixture AST is one assignment", failures)
    if not isinstance(expr, ast.Assign):
        return
    values = _resolve(expr.value, {}, "scripts/checks/check_suppressions.py")
    expect(
        [item.value for item in values] == ["path with spaces/", "two/"],
        "must fire: paths containing spaces remain concrete values, never reasons",
        failures,
    )
    reasoned = ast.parse("VALUE = (('path with spaces/', 'why'),)\n").body[0]
    expect(isinstance(reasoned, ast.Assign), "reason fixture AST is one assignment", failures)
    if isinstance(reasoned, ast.Assign):
        values = _resolve(reasoned.value, {}, "fixture.py", reasoned_pairs=True)
        expect(
            values == [PolicyValue("path with spaces/", "why")],
            "must fire: explicit pair schema accepts a one-word rationale",
            failures,
        )
    malformed = ast.parse("VALUE = (('path/', ''),)\n").body[0]
    if isinstance(malformed, ast.Assign):
        expect(
            not _resolve(malformed.value, {}, "fixture.py", reasoned_pairs=True),
            "must fire: explicit pair schema rejects an empty or ambiguous rationale",
            failures,
        )
    schema = AuthoritySchema("path-exclusion")
    original = {
        "fixture.py:EXCLUDED": ResolvedAuthority(
            "fixture.py", 1, "EXCLUDED", schema, (PolicyValue("one"), PolicyValue("two"))
        )
    }
    swapped = {
        "fixture.py:EXCLUDED": ResolvedAuthority(
            "fixture.py", 1, "EXCLUDED", schema, (PolicyValue("one"), PolicyValue("three"))
        )
    }
    expect(
        _authority_value_digest(original) != _authority_value_digest(swapped),
        "must fire: same-count authority value swaps change the authenticated digest",
        failures,
    )
 
 
def _assert_scope_registry(root: Path, failures: list[str]) -> None:
    """Assert the census classifies every constant and new names fail closed."""
    representative = {
        "scripts/checks/annot_scope.py:SCAN_DIRS",
        "scripts/checks/check_mcdc_floor.py:OUT_OF_SCOPE_PREFIXES",
        "scripts/checks/annot_clang.py:GENERATED_HEADERS",
        "scripts/checks/check_core_layering.py:HOSTED_HEADERS",
        "scripts/checks/check_magic_numbers.py:IGNORED_INT",
        "scripts/checks/line_citation_lex.py:THIRD_PARTY_RE",
        "scripts/checks/suppression_catalog.py:VENDOR_PREFIXES",
    }
    expect(
        representative <= set(AUTHORITY_SCHEMAS),
        "must fire: every reported scope-authority class has an explicit schema",
        failures,
    )
    fixture_root = root / "scope-registry-fixture"
    unknown = fixture_root / "scripts" / "checks" / "check_suppressions.py"
    unknown.parent.mkdir(parents=True)
    unknown.write_text(
        "SCAN_DIRS = ('fixture',)\nARBITRARY_NEW_ROOTS = ('fixture/',)\nplain = 1\n",
        encoding="ascii",
    )
    _authorities, problems, _diagnosed, census = _scan_scope_file(
        fixture_root, "scripts/checks/check_suppressions.py", {}
    )
    unclassified = [item for item in problems if item.code == "unclassified-checker-constant"]
    expect(
        len(unclassified) == len(census) and len(census) == EXPECTED_UNCLASSIFIED_FIXTURES,
        "must fire: unregistered constants of any name fail closed; lowercase stays out",
        failures,
    )
 
 
def _assert_scope_file_return_contract(root: Path, failures: list[str]) -> None:
    """Assert every parse outcome returns the same census-identity type."""
    rel = "scripts/checks/check_suppressions.py"
 
    valid_root = root / "scope-return-valid"
    valid = valid_root / rel
    valid.parent.mkdir(parents=True)
    valid.write_text("MAX_CHECK_DETAILS = 80\nplain = 1\n", encoding="ascii")
    _authorities, quiet, _diagnosed, census = _scan_scope_file(valid_root, rel, {})
    expect(
        not quiet and census == {f"{rel}:MAX_CHECK_DETAILS"},
        "quiet: a valid checker returns its exact census-identity set",
        failures,
    )
 
    invalid_root = root / "scope-return-invalid"
    invalid = invalid_root / rel
    invalid.parent.mkdir(parents=True)
    invalid.write_text("MAX_CHECK_DETAILS = (\n", encoding="ascii")
    _authorities, problems, _diagnosed, census = _scan_scope_file(invalid_root, rel, {})
    expect(
        census == set() and any(item.code == "checker-scope-ast" for item in problems),
        "must fire: an unreadable checker reports an AST finding with an empty census set",
        failures,
    )
    _authorities, collected, _diagnosed = _collect_authorities(invalid_root, [rel])
    expect(
        any(item.code == "checker-scope-ast" for item in collected),
        "must fire: repository collection preserves the parse finding without a type crash",
        failures,
    )
 
 
def _census_mutation_fixtures() -> dict[str, str]:
    """Return one fixture per authority-mutation route the census rejects.
 
    Kept apart from the assertion so the assertion stays about the RULE
    rather than about the table, and so a new route is added in one place.
 
    Returns:
        Label to Python source, each of which must produce a finding.
    """
    return {
        "augmented assignment": "EXEMPT_PREFIXES = ('a/',)\nEXEMPT_PREFIXES += ('hidden/',)\n",
        "mutator call": "EXEMPT_PREFIXES = ['a/']\nEXEMPT_PREFIXES.append('hidden/')\n",
        "update call": "PATH_CLASS = {'a': 'b'}\nPATH_CLASS.update({'hidden/': 'x'})\n",
        "conditional rebinding": (
            "EXEMPT_PREFIXES = ('a/',)\nif True:\n    EXEMPT_PREFIXES = ('b/',)\n"
        ),
        "double binding": "EXEMPT_PREFIXES = ('a/',)\nEXEMPT_PREFIXES = ('b/',)\n",
        "subscript store": "PATH_CLASS = {'a': 'b'}\nPATH_CLASS['hidden/'] = 'x'\n",
        "alias mutation": (
            "EXEMPT_PREFIXES = ['a/']\nALIAS = EXEMPT_PREFIXES\nALIAS.append('hidden/')\n"
        ),
        "global rebinding": (
            "EXEMPT_PREFIXES = ('a/',)\ndef f():\n"
            "    global EXEMPT_PREFIXES\n    EXEMPT_PREFIXES = ()\n"
        ),
        "deletion": "EXEMPT_PREFIXES = ('a/',)\ndel EXEMPT_PREFIXES\n",
        "imported mutation": "from check_fixture import AUTH\nAUTH.update(('hidden/',))\n",
        "imported augment": "from check_fixture import AUTH as LOCAL\nLOCAL += ('hidden/',)\n",
        "module attribute": "import check_fixture\ncheck_fixture.AUTH += ('hidden/',)\n",
        "module setattr": "import check_fixture\nsetattr(check_fixture, 'AUTH', ())\n",
        "dynamic namespace": (
            "EXEMPT_PREFIXES = ('a/',)\ndef f():\n    globals()['EXEMPT_PREFIXES'] = ()\n"
        ),
        "module attribute alias": (
            "import check_fixture as mod\nalias = mod.AUTH\nalias.update({'hidden/': 'x'})\n"
        ),
        "imported alias append": (
            "from check_fixture import AUTH\nalias = AUTH\nalias.append('hidden/')\n"
        ),
        "operator setitem": (
            "import operator\nimport check_fixture as mod\n"
            "operator.setitem(mod.AUTH, 'hidden/', 'x')\n"
        ),
        "namespace item mutation": (
            "import check_fixture as mod\nvars(mod)['AUTH'].update({'hidden/': 'x'})\n"
        ),
        "namespace replacement": ("import check_fixture as mod\nvars(mod).update({'AUTH': {}})\n"),
        "module dict store": ("import check_fixture as mod\nmod.__dict__['AUTH'] = {}\n"),
        "dynamic import chain": "__import__('check_fixture').AUTH.append('hidden/')\n",
        "module delattr": "import check_fixture as mod\ndelattr(mod, 'AUTH')\n",
        "getattr alias": (
            "import check_fixture as mod\nalias = getattr(mod, 'AUTH')\nalias.clear()\n"
        ),
        "unbound mutator": (
            "import check_fixture as mod\ndict.update(mod.AUTH, {'hidden/': 'x'})\n"
        ),
    }
 
 
def _assert_census_immutability(failures: list[str]) -> None:
    """Assert every authority mutation route is rejected and clean reads pass."""
    protected = {"EXEMPT_PREFIXES", "PATH_CLASS"}
    modules = {"check_fixture": frozenset({"AUTH"})}
    must_fire = _census_mutation_fixtures()
    for label, source in must_fire.items():
        tree = ast.parse(source)
        found = mutation_findings("fixture.py", tree, protected, modules)
        expect(bool(found), f"must fire: authority {label} is rejected", failures)
    quiet = (
        "import check_fixture as mod\n"
        "EXEMPT_PREFIXES = ('a/', 'b/')\n"
        "OTHER = tuple(sorted(EXEMPT_PREFIXES))\n"
        "def f(rel):\n"
        "    seen = set()\n"
        "    seen.update(EXEMPT_PREFIXES)\n"
        "    seen.update(mod.AUTH)\n"
        "    seen.add(rel)\n"
        "    fields = vars(rel)\n"
        "    return rel.startswith(EXEMPT_PREFIXES) and seen and fields\n"
    )
    found = mutation_findings("fixture.py", ast.parse(quiet), protected, modules)
    expect(not found, "quiet: single binding with read-only uses passes", failures)
    expect(
        _condition_dependent(ast.parse("X = ('a',) if True else ('b',)").body[0].value)
        and not _condition_dependent(ast.parse("X = ('a', 'b')").body[0].value),
        "must fire: condition-dependent authority values are detected exactly",
        failures,
    )
    expression_schema = AuthoritySchema("suppression-control-plane", "expression-digest")
    original = ast.parse("X = ('safe',) if flag else ('closed',)").body[0].value
    mutated = ast.parse("X = ('safe',) if not flag else ('closed',)").body[0].value
    original_values = _resolve_registered(original, {}, "fixture.py", expression_schema)
    mutated_values = _resolve_registered(mutated, {}, "fixture.py", expression_schema)
    expect(
        _condition_dependent(original)
        and len(original_values) == 1
        and original_values[0].value.startswith("sha256:"),
        "quiet: expression digest authenticates a conditional security authority",
        failures,
    )
    expect(
        original_values != mutated_values,
        "must fire: expression digest changes with conditional security logic",
        failures,
    )
 
 
def _census_sink_fixtures() -> tuple[str, ...]:
    """Return one fixture per way a scope literal can reach a filter sink.
 
    Returns:
        Python sources that must each yield an inline-scope-literal finding.
    """
    return (
        "def f(rel):\n    return rel.startswith(('libs/third_party/', 'x/'))\n",
        "def f(rel):\n    excluded = {'third_party', 'build'}\n"
        "    return any(p in excluded for p in rel.parts)\n",
        "def f(rel):\n    return any(p in {'a', 'b'} for p in rel.parts)\n",
        "def f(rel):\n    scope = ('evil/',)\n    return rel.startswith(scope)\n",
        "def f(rel):\n    scope = ('evil/',)\n    return rel.endswith(scope)\n",
        "def f(path):\n    parts = {'vendor', 'generated'}\n"
        "    return bool(parts & set(path.parts))\n",
        "def f(rel):\n    return (scope := ('evil/',)) and rel.startswith(scope)\n",
        "def f(rel):\n    scope = ['evil/']\n    alias = scope\n"
        "    return rel.startswith(tuple(alias))\n",
        "def f(rel, flag):\n    return rel.startswith(('evil/',) if flag else ('other/',))\n",
        "def outer(rel):\n    scope = ('evil/',)\n"
        "    def inner():\n        return rel.startswith(scope)\n    return inner\n",
    )
 
 
def _assert_census_sinks(failures: list[str]) -> None:
    """Assert inline scope literals in filter sinks fail while authorities pass."""
    must_fire = _census_sink_fixtures()
    for source in must_fire:
        found = sink_findings("fixture.py", ast.parse(source))
        expect(
            any(item.code == "inline-scope-literal" for item in found),
            "must fire: inline scope literal reaches a filter sink",
            failures,
        )
    quiet = (
        "AUTH = ('libs/third_party/',)\nPARTS = frozenset({'third_party'})\n"
        "def f(rel, path):\n"
        "    a = rel.startswith(AUTH)\n"
        "    b = any(p in PARTS for p in path.parts)\n"
        "    c = rel.startswith(('#', '//'))\n"
        "    d = rel.startswith(tuple(AUTH))\n"
        "    e = path.suffix in {'.c', '.h'}\n"
        "    names = ['alpha', 'beta']\n"
        "    names.append('gamma')\n"
        "    return a or b or c or d or e or names\n"
        "def selftest(scope, failures):\n"
        "    expect(\n"
        "        not any(s.startswith(('libs/third_party/', 'x/')) for s in scope),\n"
        "        'vendored SOUP stays out of scope',\n"
        "        failures,\n"
        "    )\n"
        "    assert all(p not in {'a/b'} for p in scope)\n"
    )
    found = sink_findings("fixture.py", ast.parse(quiet))
    expect(
        not found,
        "quiet: declared authorities, non-path tokens, and test expectations pass sinks",
        failures,
    )
    bindings = census_bindings(
        ast.parse(
            "A = 1\nB: int = 2\nC, D = 3, 4\nA += 1\nlower = 5\ndef f():\n    E = 6\n    return E\n"
        )
    )
    expect(
        [name for name, _line, _value in bindings] == ["A", "B", "C", "D", "A"],
        "must fire: census sees every module-level constant binding form only",
        failures,
    )
    walrus = census_bindings(
        ast.parse("_ = (ROOTS := ('evil/',))\ndef f():\n    (LOCAL := 1)\n    return LOCAL\n")
    )
    expect(
        [name for name, _line, _value in walrus] == ["ROOTS"],
        "must fire: a module-level walrus constant is censused, a function-local one is not",
        failures,
    )
 
 
def _assert_census_shapes(failures: list[str]) -> None:
    """Assert non-authority categories reject scope-shaped values."""
    tuple_value = ast.parse("X = ('a', 'b')").body[0].value
    regular_checker = "scripts/checks/check_suppressions.py"
    selftest_checker = "scripts/checks/suppression_governance_selftest.py"
    fixture_publishers = (
        "scripts/checks/hil_convergence_safety_runtime_loader_harness.py",
        "scripts/checks/hil_convergence_safety_runtime_sources.py",
    )
    unreviewed_publisher = (
        "scripts/checks/unreviewed_runtime_sources.py"  # PATHREF-OK: non-publisher fixture
    )
    list_value = ast.parse("X = ['a', 'b']").body[0].value
    int_value = ast.parse("X = 42").body[0].value
    scope_value = ast.parse("X = 'libs/third_party/'").body[0].value
    plain_text = ast.parse("X = 'run the gate'").body[0].value
    expect(
        shape_problem(regular_checker, "numeric-format", list_value, has_selftest=False) is not None
        and shape_problem(regular_checker, "exit-code", tuple_value, has_selftest=False)
        is not None,
        "must fire: container values contradict numeric categories",
        failures,
    )
    expect(
        shape_problem(regular_checker, "diagnostic-text", scope_value, has_selftest=False)
        is not None,
        "must fire: a path-prefix literal is scope-shaped in any non-authority",
        failures,
    )
    expect(
        shape_problem(regular_checker, "selftest-fixture", plain_text, has_selftest=False)
        is not None,
        "must fire: selftest-fixture classification outside a selftest module",
        failures,
    )
    expect(
        shape_problem(unreviewed_publisher, "selftest-fixture", int_value, has_selftest=False)
        is not None,
        "must fire: unreviewed fixture publisher cannot own selftest fixtures",
        failures,
    )
    expect(
        shape_problem(regular_checker, "numeric-format", int_value, has_selftest=False) is None
        and shape_problem(regular_checker, "diagnostic-text", plain_text, has_selftest=False)
        is None
        and shape_problem(selftest_checker, "selftest-fixture", plain_text, has_selftest=False)
        is None,
        "quiet: matching shapes pass their categories",
        failures,
    )
    expect(
        all(
            shape_problem(publisher, "selftest-fixture", int_value, has_selftest=False) is None
            for publisher in fixture_publishers
        ),
        "quiet: reviewed fixture publishers own fixture publication data",
        failures,
    )
 
 
def _assert_nonfatal_parsers(root: Path, failures: list[str]) -> None:
    """Assert declarations and resolved shell invocations model effective modes."""
    tree = ast.parse(
        """import argparse
p = argparse.ArgumentParser()
p.add_argument('--warn', action='store_true', help='fixture advisory mode')
"""
    )
    rows, findings = _option_declarations("scripts/checks/check_world_tags.py", tree)
    expect(
        len(rows) == 1 and not findings,
        "must fire: argparse nonfatal availability is a declaration row",
        failures,
    )
    fixture_root = root / "nonfatal-usage-fixture"
    caller = fixture_root / "scripts" / "ci" / "gates" / "checks.sh"
    caller.parent.mkdir(parents=True, exist_ok=True)
    caller.write_text(
        """python3 scripts/checks/check_world_tags.py --warn
checker=scripts/checks/check_world_tags.py; python3 "$checker" --warn
checker_argv=(python3 scripts/checks/check_world_tags.py --warn)
"${checker_argv[@]}"
local local_checker=scripts/checks/check_world_tags.py; python3 "$local_checker" --warn
readonly readonly_checker=scripts/checks/check_world_tags.py; python3 "$readonly_checker" --warn
local -a local_argv=(python3 scripts/checks/check_world_tags.py)
local_argv+=(--warn)
"${local_argv[@]}"
bash -c "python3 scripts/checks/check_world_tags.py --warn"
python3 scripts/checks/check_world_tags.py
python3 scripts/checks/cite_check.py --require-cites
python3 scripts/checks/check_world_tags.py --strict
python3 scripts/checks/cite_check.py --require-cites --strict
echo scripts/checks/check_world_tags.py --warn
# python3 scripts/checks/check_world_tags.py --warn
""",
        encoding="ascii",
    )
    quiet = caller.with_name("hygiene.sh")
    quiet.write_text(
        'text="scripts/checks/check_world_tags.py --warn"\necho "$text"\n',
        encoding="ascii",
    )
    rows = _active_usages(
        fixture_root,
        ["scripts/ci/gates/checks.sh", "scripts/ci/gates/hygiene.sh"],
    )
    expect(
        len(rows) == EXPECTED_NONFATAL_FIXTURE_ROWS
        and all(item.directive == "nonfatal-invocation" for item in rows),
        "must fire: direct/default/static-shell and declared scalar/argv callers only",
        failures,
    )
 
 
def _assert_checker_control_parsers(root: Path, failures: list[str]) -> None:
    """Run explicit scope and nonfatal control-plane assertions."""
    _assert_scope_value_semantics(failures)
    _assert_scope_registry(root, failures)
    _assert_scope_file_return_contract(root, failures)
    _assert_census_immutability(failures)
    _assert_census_sinks(failures)
    _assert_census_shapes(failures)
    _assert_nonfatal_parsers(root, failures)
 
 
def assert_governance_parsers(root: Path, failures: list[str]) -> None:
    """Run every new governance family in both directions."""
    _assert_generated(root, failures)
    _assert_config_parsers(failures)
    _assert_bound_markers(root, failures)
    _assert_language_controls(failures)
    _assert_cmake_bracket_lexing(failures)
    _assert_hardware_binding(root, failures)
    _assert_checker_control_parsers(root, failures)