Repository navigation
feat(kernel): implement safety kernel verification and explanation (Phase 4B) - #29
Merged
Merged
Conversation
Establish the foundational safety kernel DSL and evaluation context. KernelContext encapsulates system facts, declared plan diffs, and Z3 constant bindings, enforcing the zero-default safety invariant by raising MissingFact on any absent fact. Add Invariant Protocol for formal SMT invariant definitions and configure Z3 typing overrides. Implements build-plan step B4.1.
Implement FactExtractor and subsystem extraction routines for Kubernetes, GitHub, the run store, the dependency graph, rehearsal evidence, remediation plans, and configuration per docs/03-invariants.md §3.3. Every extracted fact is stamped with observed_at. Enforce zero-default safety discipline by omitting unavailable facts rather than guessing default values, so KernelContext detects missing facts and yields UNCERTAIN. Expand Fact.source contract to include 'store' and 'plan'. Provide golden fact fixtures for checkpoint verification and achieve 100% line and branch test coverage. Implements build-plan step B4.2.
Encodes the eight PROOF invariants in Z3 SMT logic to ensure that remediation plans are proved safe before production actuation. Enforces zero-default safety across all invariants: any missing fact immediately raises MissingFact to yield an UNCERTAIN verdict rather than assuming a permissive default. Implements build-plan steps B4.3a–B4.3h: - K1 (B4.3a): Replica floor preservation during scale and rolling restart - K2 (B4.3b): Strict authorization scope to single target namespace - K3 (B4.3c): Rollback boundary forbidding traversal of schema migrations - K9 (B4.3d): Strict reversibility and target set equality for active plans - K4 (B4.3e): Two-stage containment of observed and declared blast sets - K5 (B4.3f): Single active writer mutex over concurrent plan targets - K7 (B4.3g): Production mutation budget ceiling in rolling time windows - K8 (B4.3h): Evidence freshness, density, and mirror fidelity gating
Safety kernel formal verification requires evaluating candidate remediation plans against the eight PROOF invariants using Z3 scoped negation checks. Counterexamples are rendered into actionable human explanations and unsat cores, while timeouts (5 s ceiling) and missing facts produce an UNCERTAIN verdict without defaulting in accordance with zero-default safety rules. Adds the CLI command ust kernel verify and updates K3 to support commit-subscripted migration facts. Implements build-plan step B4.4.
Formal safety guarantees require that documentation and code remain strictly synchronized so that verification invariants published in docs/03-invariants.md match runtime and solver semantics. Adds the invariant catalogue generator, K6 and K10 runtime invariant definitions, documentation update and verification routines, CLI command `ust kernel catalogue`, and automated CI parity tests ensuring 100% line and branch test coverage. Implements build-plan step B4.5.
Incident responders on-call need immediate, unambiguous understanding of why the formal safety kernel vetoed a candidate remediation plan, which observed facts triggered the invariant violation, and concrete solver counterexamples and actionable guidance to unblock remediation. Implements understudy.kernel.explain with structured VetoExplanation, Z3 solver model value extraction, invariant-specific guidance for all formal PROOF invariants (K1–K9), and delegation from render_veto_reason. Adds the CLI command ust kernel explain and --explain flag on verify. Maintains 100% statement and branch test coverage across the repository. Implements build-plan step B4.6.
Resolve all 7 Standards and 8 Spec review findings across the safety kernel implementation. Enforce strict type annotations across test helpers to eliminate all # type: ignore silencing, refactor explain_veto into modular per-invariant explainer functions with strict Protocol typing to remove large switch smell, eliminate late imports and # noqa directives in api.py, extract shared CLI plan and facts validation logic, ensure transitive closure in graph fact extraction and K4 blast containment, tighten zero-default rules for plan target namespaces and missing timestamps, and enforce uncertain verdict precedence over veto when facts are missing. Implements build-plan step B4.4.
Owner
Author
📋 Code Review Findings & Resolution Report (Phase 4B — Safety Kernel)All 7 Standards and 8 Specification findings identified in the Phase 4B code review have been addressed and resolved. Full regression tests, static analysis, and Checkpoint B4 command verifications are green at 100.00% branch and statement coverage. 1. Standards Findings & Resolutions
2. Specification Findings & Resolutions
3. Verification & CI Status
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Build-Plan Step Implemented
kernel/dsl.py: Invariant Protocol and KernelContext with Z3 constants & zero-default disciplinekernel/facts.py: Fact extraction from Kubernetes, GitHub, Store, Graph, and Tournamentkernel/invariants/: Formal SMT encodings for K1, K2, K3, K4, K5, K6, K7, K8, K9, K10kernel/verify.py: Three-valued verification (pass,veto,uncertain) with Z3 scoped negation checkskernel/catalogue.py: Invariant catalogue generation and markdown docs parity CI testskernel/explain.py: Veto rendering into actionable operator prose, failing facts, and counterexamplesCheckpoint Execution & Output
Observed outputs for all Checkpoint B4 commands:
ADRs Relied On
UNCERTAIN)Mock Registry Disclosures
Documentation Updates
CHECKLIST.mdmarking B4.1 through B4.6 complete.docs/03-invariants.mdis strictly synchronized and verified bit-for-bit with the invariant catalogue.Definition of Done
make checkgreen (ruff, mypy --strict, import-linter, pytest)# MOCKED:marker without a row in docs/MOCKS.md