#!/usr/bin/env python3 """Check user-engine against the NetKingdom security layer model (§5, §11). Read-only. user-engine is Engine/PIP and holds no catalogued Tooling client. PostgreSQL is the modeled-concept store, declared under own_store. INTENT.md frontmatter governs the layer; layer.yaml is its derived form. The failure this exists to catch is a convenience: an OpenBao, Vault, LDAP, or cluster client arriving as one import. That is an undeclared violation. Every run prints the standard text it checks against (VALIDATED_AGAINST) and the scope it ranged over (SCOPE), on the OK line and in --report. The version lives in the run, not in the declaration (GH-DEC-2026-020, A12 r2). Exit 0 clean, 1 undeclared contact found, 2 declaration malformed. """ from __future__ import annotations import argparse import ast import re import sys from pathlib import Path ROOT = Path(__file__).resolve().parents[1] SRC = ROOT / "src" / "user_engine" DECL = ROOT / "layer.yaml" INTENT = ROOT / "INTENT.md" sys.path.insert(0, str(ROOT / "src")) from user_engine.layer_yaml import load_mapping, load_mapping_text # noqa: E402 # The standard text this checker was built and validated against. The version # belongs to the run, not to the declaration (GH-DEC-2026-020 §4, A12 r2); it is # printed on every run. Bump it when the checker is re-validated. VALIDATED_AGAINST = "net-kingdom/canon/standards/security-layer-model_v0.7.md" # What every run ranges over. Stance, claims and classification maps # (pep-stance.yaml) are not declarations and are not checked for versions # (GH-DEC-2026-020 §3). SCOPE = ( "declaration: INTENT.md frontmatter + layer.yaml (all keys and values); " "imports: src/user_engine/**/*.py" ) # A12 r2: no standard or companion version in any key or value of the # declaration. Comments are not parsed; schema_version is not reached. VERSION_KEY = re.compile(r"(?:^|_)version$", re.IGNORECASE) VERSION_VALUE = re.compile(r"(?:^|[_\-/\s])v?\d+\.\d+(?:\.\d+)*(?:\.md)?(?=$|[\s/])|_v\d+", re.IGNORECASE) UNREACHED_KEYS = {"schema_version"} TOOLING_IMPORTS = { "hvac": "OpenBao / Vault client", "bao": "OpenBao client", "kubernetes": "cluster client", "kubernetes_asyncio": "cluster client", "ldap3": "direct LDAP client (key-cape tooling)", "python_ldap": "direct LDAP client (key-cape tooling)", "docker": "container runtime client", "redis": "direct datastore connection", } OWN_STORE_IMPORTS = { "psycopg": "PostgreSQL modeled-concept store", "psycopg2": "PostgreSQL modeled-concept store", "asyncpg": "PostgreSQL modeled-concept store", "sqlalchemy": "database client", "pymysql": "database client", } # §3's vocabulary is closed at four tokens and compared after an ASCII # case-fold (GH-DEC-2026-017 §2, §3, amendment A9). Nothing is re-spelled. LAYER_VOCABULARY = {"taxonomy", "tooling", "engine", "staff"} def fold(value: object) -> str: """ASCII case-fold only: non-ASCII letters are left untouched.""" return "".join( chr(ord(c) + 32) if "A" <= c <= "Z" else c for c in str(value).strip() ) def find_versions(node: object, where: str, path: str = "") -> list[str]: """Every key or value in a declaration that carries a version (A12 r2).""" found: list[str] = [] if isinstance(node, dict): for key, value in node.items(): here = f"{path}.{key}" if path else str(key) if str(key) in UNREACHED_KEYS: continue if VERSION_KEY.search(str(key)): found.append(f"{where}: key '{here}'") continue found.extend(find_versions(value, where, here)) elif isinstance(node, list): for index, item in enumerate(node): found.extend(find_versions(item, where, f"{path}[{index}]")) elif isinstance(node, str) and VERSION_VALUE.search(node): found.append(f"{where}: value of '{path}' = {node!r}") return found def reject_versions(data: dict, where: str) -> None: found = find_versions(data, where) if found: print( "FAIL: a layer declaration MUST NOT carry a standard or companion " "version in any key or value (GH-DEC-2026-017 §5, GH-DEC-2026-020, A12 r2)", file=sys.stderr, ) for item in found: print(f" {item}", file=sys.stderr) raise SystemExit(2) def load_intent_layer() -> str: """Return the governing `layer:` value from INTENT.md frontmatter (§11).""" try: text = INTENT.read_text() except OSError as exc: print(f"FAIL: cannot read {INTENT.name}: {exc}", file=sys.stderr) raise SystemExit(2) from exc parts = text.split("---", 2) if not text.startswith("---") or len(parts) < 3: print(f"FAIL: {INTENT.name} has no frontmatter (§11)", file=sys.stderr) raise SystemExit(2) try: front = load_mapping_text(parts[1]) except ValueError as exc: print(f"FAIL: {INTENT.name} frontmatter is not parseable: {exc}", file=sys.stderr) raise SystemExit(2) from exc reject_versions(front, f"{INTENT.name} frontmatter") if "layer" not in front: print(f"FAIL: {INTENT.name} frontmatter has no 'layer:' key (§11)", file=sys.stderr) raise SystemExit(2) return str(front["layer"]) def load_declaration() -> dict: if not DECL.exists(): print(f"FAIL: no declaration at {DECL.relative_to(ROOT)} (§11)", file=sys.stderr) raise SystemExit(2) try: data = load_mapping(DECL) except (ValueError, OSError) as exc: print(f"FAIL: {DECL.name} is not parseable: {exc}", file=sys.stderr) raise SystemExit(2) from exc # No standard_version: a layer declaration MUST NOT carry one # (GH-DEC-2026-017 §4, amendment A12). Its presence is malformed. for key in ("layer", "role", "repository", "tooling_contacts", "derived", "derived_from"): if key not in data: print(f"FAIL: {DECL.name} missing required key '{key}' (§11)", file=sys.stderr) raise SystemExit(2) reject_versions(data, DECL.name) if data["derived"] is not True or data["derived_from"] != "INTENT.md": print( f"FAIL: {DECL.name} must be marked derived: true, derived_from: INTENT.md " "(§11 derived-artifact rule, GH-DEC-2026-017, A11)", file=sys.stderr, ) raise SystemExit(2) if fold(data["layer"]) not in LAYER_VOCABULARY: print( f"FAIL: declared layer {data['layer']!r} is not a §3 token " f"({', '.join(sorted(LAYER_VOCABULARY))}, case-insensitive)", file=sys.stderr, ) raise SystemExit(2) intent_layer = load_intent_layer() if fold(intent_layer) != fold(data["layer"]): # A finding in its own right; INTENT.md governs but the disagreement # is reported, not resolved away by precedence (A11). print( f"FAIL: INTENT.md declares layer {intent_layer!r} but {DECL.name} " f"declares {data['layer']!r}; they disagree after case-folding", file=sys.stderr, ) raise SystemExit(2) if fold(intent_layer) != "engine": print( f"FAIL: declared layer is {intent_layer!r}, expected Engine", file=sys.stderr, ) raise SystemExit(2) if str(data["role"]).lower() != "pip": print(f"FAIL: declared role is {data['role']!r}, expected 'pip'", file=sys.stderr) raise SystemExit(2) if data["tooling_contacts"] not in ([], None): print( "FAIL: tooling_contacts must be empty; catalogued Tooling clients " "are undeclared violations for this Engine", file=sys.stderr, ) raise SystemExit(2) return data def imported_modules(path: Path) -> set[str]: try: tree = ast.parse(path.read_text()) except SyntaxError: return set() found: set[str] = set() for node in ast.walk(tree): if isinstance(node, ast.Import): found.update(alias.name.split(".")[0] for alias in node.names) elif isinstance(node, ast.ImportFrom): if node.level == 0 and node.module: found.add(node.module.split(".")[0]) return found def scan() -> list[tuple[Path, str, str]]: hits: list[tuple[Path, str, str]] = [] for path in sorted(SRC.rglob("*.py")): for module in sorted(imported_modules(path)): if module in TOOLING_IMPORTS: hits.append((path, module, TOOLING_IMPORTS[module])) return hits def scan_own_store() -> list[tuple[Path, str, str]]: hits: list[tuple[Path, str, str]] = [] for path in sorted(SRC.rglob("*.py")): for module in sorted(imported_modules(path)): if module in OWN_STORE_IMPORTS: hits.append((path, module, OWN_STORE_IMPORTS[module])) return hits def main() -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--report", action="store_true", help="print the declaration summary") args = parser.parse_args() decl = load_declaration() hits = scan() own_store_hits = scan_own_store() own_store = decl.get("own_store") or [] if args.report: print( f"user-engine — layer {decl['layer']}/{decl['role']} " f"(derived from {decl['derived_from']})" ) print(f" checked against: {VALIDATED_AGAINST}") print(f" scope: {SCOPE}") print(" tooling contacts declared: 0") print(f" own-store declarations: {len(own_store)}") print(f" own-store imports: {len(own_store_hits)}") print(f" pep stance: {decl.get('pep_stance')}") if hits: print("", file=sys.stderr) print( "FAIL: undeclared Tooling-layer client (§11 undeclared violation)", file=sys.stderr, ) for path, module, what in hits: print(f" {path.relative_to(ROOT)}: imports {module!r} — {what}", file=sys.stderr) return 1 if own_store_hits and not own_store: print( "FAIL: modeled-concept store import with no own_store declaration", file=sys.stderr, ) for path, module, what in own_store_hits: print(f" {path.relative_to(ROOT)}: imports {module!r} — {what}", file=sys.stderr) return 1 if not args.report: print( f"OK: no catalogued Tooling client in {SRC.relative_to(ROOT)} " f"(Engine/PIP, §11); checked against {VALIDATED_AGAINST}; scope: {SCOPE}" ) return 0 if __name__ == "__main__": raise SystemExit(main())