secrets-engine/scripts/check_layer_conformance.py

#!/usr/bin/env python3
"""Check secrets-engine against the NetKingdom security layer model (§3.3, §6, §11).

Read-only. This is the Engine/Lifecycle adaptation of the ops-warden reference
checker. §5 Staff shapes do not apply to the owned OpenBao contact.

Two declaration forms are read. Per GH-DEC-2026-017 §1 (amendment A11)
INTENT.md's frontmatter `layer:` key governs; layer.yaml is a derived artifact
that must be marked derived, must name INTENT.md, and must agree with it. The
sidecar is still read, because a disagreement between the two is a finding in
its own right, reported rather than resolved away by precedence.

Layer values are compared against §3's closed four-token vocabulary after an
ASCII case-fold (GH-DEC-2026-017 §2-§3, amendment A9). Nothing is re-spelled:
`Engine` and `engine` are one token. Neither form carries a standard version
(GH-DEC-2026-017 §5, amendment A12), and its return is rejected.

Mechanical checks:

- INTENT.md frontmatter carries the governing `layer:` (Engine) and role
- layer.yaml is marked derived from INTENT.md and agrees with it after folding
- no authorization decision surface is exposed
- the PEP stance map is published at the path named in the declaration
- every OpenBao subprocess adapter lives in a module listed as owned tooling

Exit 0 clean, 1 finding, 2 declaration malformed.
"""
from __future__ import annotations

import argparse
import re
import sys
from pathlib import Path

import yaml

ROOT = Path(__file__).resolve().parents[1]
SRC = ROOT / "src" / "secrets_engine"
DECL = ROOT / "layer.yaml"
INTENT = ROOT / "INTENT.md"

BAO_ARGV = re.compile(
    r"""\[\s*(?:["']bao["']|bao_bin\b|bao_binary\b|self\.bao_bin)\s*,"""
)
DECISION_SURFACE = re.compile(
    r"""\b(evaluate_policy|check_permission|render_decision|pdp_decide)\b"""
)

# §3's vocabulary: closed, four tokens, compared case-insensitively
# (GH-DEC-2026-017 §3, amendment A9). Taxonomy is in it.
LAYER_VOCABULARY = {"taxonomy", "tooling", "engine", "staff"}
EXPECTED_LAYER = "engine"


def _fold(value: object) -> str:
    """ASCII case-fold, per §3 as amended: two spellings of a token are one token."""
    return str(value).strip().encode("ascii", "ignore").decode().lower()


def _no_standard_version(where: str, data: dict) -> None:
    if "standard_version" in data:
        print(
            f"MALFORMED: {where} carries 'standard_version' — a layer declaration "
            "MUST NOT carry a standard version (§11 as amended by A12)"
        )
        raise SystemExit(2)


def _in_vocabulary(where: str, layer: object) -> None:
    if _fold(layer) not in LAYER_VOCABULARY:
        print(
            f"MALFORMED: {where} declares layer {layer!r}, outside §3's closed "
            f"vocabulary {sorted(LAYER_VOCABULARY)} (case-insensitive)"
        )
        raise SystemExit(2)


def load_declaration() -> dict:
    if not DECL.exists():
        print(f"MISSING: {DECL} — secrets-engine must declare in its own voice (§11)")
        raise SystemExit(2)
    decl = yaml.safe_load(DECL.read_text())
    for key in (
        "layer",
        "role",
        "repository",
        "derived",
        "derived_from",
        "owned_tooling",
        "decision_surfaces_exposed",
        "pep_shaped",
        "pep_stance",
    ):
        if key not in decl:
            print(f"MALFORMED: layer.yaml has no {key!r}")
            raise SystemExit(2)
    # §11 derived-artifact rule (GH-DEC-2026-017 §1): marked, naming its source.
    if decl["derived"] is not True:
        print("MALFORMED: layer.yaml must be marked 'derived: true' (§11, GH-DEC-2026-017 §1)")
        raise SystemExit(2)
    if decl["derived_from"] != "INTENT.md":
        print(
            f"MALFORMED: layer.yaml derives from {decl['derived_from']!r}; §11 names "
            "INTENT.md as the governing declaration"
        )
        raise SystemExit(2)
    _no_standard_version("layer.yaml", decl)
    _in_vocabulary("layer.yaml", decl["layer"])
    if decl["role"] != "lifecycle":
        print(f"MALFORMED: declared role is {decl['role']!r}, expected 'lifecycle'")
        raise SystemExit(2)
    if decl["repository"] != "secrets-engine":
        print(f"MALFORMED: repository is {decl['repository']!r}")
        raise SystemExit(2)
    return decl


def intent_frontmatter() -> dict:
    text = INTENT.read_text(encoding="utf-8")
    if not text.startswith("---"):
        print("MALFORMED: INTENT.md has no YAML frontmatter (§11 / companion §2)")
        raise SystemExit(2)
    end = text.find("\n---", 3)
    if end < 0:
        print("MALFORMED: INTENT.md frontmatter is unclosed")
        raise SystemExit(2)
    front = yaml.safe_load(text[3:end]) or {}
    if "layer" not in front:
        print("MALFORMED: INTENT.md frontmatter has no 'layer' key — §11's declaration")
        raise SystemExit(2)
    _no_standard_version("INTENT.md frontmatter", front)
    _in_vocabulary("INTENT.md frontmatter", front["layer"])
    return front


def owned_modules(decl: dict) -> set[str]:
    names: set[str] = set()
    for entry in decl.get("owned_tooling", []):
        for module in entry.get("modules", []):
            names.add(Path(module).name)
    return names


def scan_bao_modules() -> dict[str, list[int]]:
    found: dict[str, list[int]] = {}
    for path in sorted(SRC.rglob("*.py")):
        hits: list[int] = []
        for n, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
            stripped = line.strip()
            if stripped.startswith("#"):
                continue
            if BAO_ARGV.search(line):
                hits.append(n)
        if hits:
            found[path.name] = hits
    return found


def scan_decision_surfaces() -> dict[str, list[int]]:
    found: dict[str, list[int]] = {}
    for path in sorted(SRC.rglob("*.py")):
        hits: list[int] = []
        for n, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
            if DECISION_SURFACE.search(line):
                hits.append(n)
        if hits:
            found[path.name] = hits
    return found


def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("--report", action="store_true")
    args = ap.parse_args()

    front = intent_frontmatter()
    decl = load_declaration()
    ok = True

    governing = front["layer"]
    if _fold(governing) != EXPECTED_LAYER:
        ok = False
        print(f"FINDING: INTENT.md frontmatter layer is {governing!r}, not Engine")
    # §11 as amended (A11): a post-fold disagreement between the two forms is a
    # finding in its own right, reported rather than resolved by precedence.
    if _fold(decl["layer"]) != _fold(governing):
        ok = False
        print(
            "FINDING: DECLARATION DISAGREEMENT (§11) — "
            f"INTENT.md (governs) layer: {governing!r}; "
            f"layer.yaml (derived) layer: {decl['layer']!r}. "
            "Case is already folded; this is a disagreement about a layer."
        )
    if str(front.get("role", "")).lower() != "lifecycle":
        ok = False
        print("FINDING: INTENT.md frontmatter role is not Lifecycle")

    if decl["decision_surfaces_exposed"] not in {None, "none"}:
        ok = False
        print("FINDING: decision_surfaces_exposed is not none — §6 forbids a second PDP")

    surfaces = scan_decision_surfaces()
    if surfaces:
        ok = False
        print("FINDING: possible authorization decision surface in source:")
        for name, lines in sorted(surfaces.items()):
            print(f"  src/secrets_engine/{name}: line(s) {', '.join(map(str, lines[:6]))}")

    stance = ROOT / str(decl["pep_stance"])
    if decl.get("pep_shaped") and not stance.is_file():
        ok = False
        print(f"FINDING: pep_shaped but {decl['pep_stance']} is missing (§6.4 / §13.1)")

    classification = decl.get("evidence_bound", {}).get("classification")
    if classification and not (ROOT / str(classification)).is_file():
        ok = False
        print(f"FINDING: evidence classification {classification} is missing (§9.6)")

    found = scan_bao_modules()
    owned = owned_modules(decl)
    undeclared = {name: lines for name, lines in found.items() if name not in owned}
    if undeclared:
        ok = False
        print("FINDING: OpenBao adapter outside owned_tooling modules:")
        for name, lines in sorted(undeclared.items()):
            print(f"  src/secrets_engine/{name}: line(s) {', '.join(map(str, lines[:6]))}")

    if args.report:
        print(
            f"{decl['repository']} — layer: {governing} role: {front.get('role')} "
            "(declared in INTENT.md; §11 governing form)"
        )
        print(f"layer.yaml: derived from {decl['derived_from']}, layer: {decl['layer']}")
        print(f"declared by {decl['declared_by']}")
        print(f"pep stance: {decl['pep_stance']}")
        print(f"owned OpenBao modules: {sorted(owned)}")
        print(f"OpenBao argv adapters found: {sorted(found)}")

    if ok and not args.report:
        print(
            "PASS — Engine/Lifecycle declaration present, no decision surface, "
            f"{len(found)} OpenBao adapter module(s) owned."
        )
    elif ok:
        print("\nPASS — declaration, owned tooling, and PEP stance path hold.")
    return 0 if ok else 1


if __name__ == "__main__":
    sys.exit(main())