{"id":50446814,"url":"https://github.com/verilean/gungnir-operator","last_synced_at":"2026-05-31T22:02:06.310Z","repository":{"id":336999921,"uuid":"1151171228","full_name":"Verilean/gungnir-operator","owner":"Verilean","description":"Formally Verified Valkey Operator","archived":false,"fork":false,"pushed_at":"2026-02-15T13:53:08.000Z","size":181,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T00:29:33.347Z","etag":null,"topics":["kubernetes-operator","lean4","valkey"],"latest_commit_sha":null,"homepage":"","language":"Lean","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Verilean.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T06:13:18.000Z","updated_at":"2026-04-04T11:06:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Verilean/gungnir-operator","commit_stats":null,"previous_names":["verilean/gungnir-operator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Verilean/gungnir-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Verilean%2Fgungnir-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Verilean%2Fgungnir-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Verilean%2Fgungnir-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Verilean%2Fgungnir-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Verilean","download_url":"https://codeload.github.com/Verilean/gungnir-operator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Verilean%2Fgungnir-operator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33750474,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kubernetes-operator","lean4","valkey"],"created_at":"2026-05-31T22:02:05.257Z","updated_at":"2026-05-31T22:02:06.300Z","avatar_url":"https://github.com/Verilean.png","language":"Lean","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Project Gungnir: Formally Verified Valkey Operator\n\n\u003e \"Named after the mythological spear that never misses its mark.\"\n\n**Project Gungnir** is a Kubernetes Operator for [Valkey](https://valkey.io/), designed to provide mathematically guaranteed reliability through **Lean 4** formal verification following the [Anvil](https://github.com/anvil-verifier/anvil) (OSDI'24) patterns.\n\n## Project Status\n\n| Metric | Value |\n|--------|-------|\n| Lean files | 18 (17 library + 1 Main.lean daemon) |\n| Docker build | Passes, produces native `gungnir_operator` binary |\n| Helm chart | Complete at `charts/gungnir-operator/` |\n| Deployed | Running on K8s with leader election, replication |\n| Proved theorems | 73 (38 in Main.lean, 35 in library) |\n| Sorry remaining | **0** (4 TCB axioms in RESP3.lean) |\n| CRD API group | `valkey.verilean.io/v1` |\n\n### Trusted Computing Base (TCB)\n\n4 axioms in `RESP3.lean` — language-level ByteArray/String properties, not operator logic gaps:\n- `utf8_roundtrip`, `byteArray_append_size`, `findCRLF_at_crlf`, `parse_unparse_roundtrip`\n\n### Proved (0 sorry across all files)\n\n- **Invariants.lean**: 10 safety invariants (`atMostOneMaster`, `ownerRefConsistency`, `noConcurrentUpdates`, `sentinelForwardProgress`, `leaderElectionSafety`, `reconcileStepValid`, `partitionSafety`, `serviceConsistency`, `noDoubleFailover`, `pdbProtectsMaster`)\n- **Liveness.lean**: 9 liveness theorems (`livenessTheorem`, `esr_holds`, `reconcileTerminates_holds`, `failedMasterReplaced_holds`, `failedNodeDetected_holds`, `reconcileStep_decreases_measure`, `phase0/1/6_eventually_holds`)\n- **ReplicaSelection.lean**: 8 theorems (`select_best_replica_total`, `replicaLessThan_total`, `replicaLessThan_trans`, `selected_has_best_priority`, `selection_maximizes_data_safety`, etc.)\n- **TemporalLogic.lean**: 4 lemmas (`wf1_rule`, `leadsTo_trans`, `eventually_mono`, `always_suffix`)\n- **Main.lean**: 38 theorems covering reconciler properties, leader election, resource creation, CR health map isolation\n- **RESP3.lean**: 1 theorem + 4 axioms (TCB)\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────┐\n│  Gungnir Operator (Lean 4 binary)   │\n│  ┌──────────┐  ┌─────────────────┐  │\n│  │ Reconciler│  │ Sentinel (FSM)  │  │\n│  │  (FSM)   │  │ Health → SDOWN  │  │\n│  │ Init→Get │  │ → Select → Pro- │  │\n│  │ →Create  │  │   mote → Reconf │  │\n│  │ →Update  │  │   → UpdateSvc   │  │\n│  │ →Health  │  │   → Done        │  │\n│  └──────────┘  └─────────────────┘  │\n│  ┌──────────────────────────────┐   │\n│  │ kubectl bridge (JSON → exec) │   │\n│  └──────────────────────────────┘   │\n└─────────────────────────────────────┘\n         │ kubectl apply/exec\n         ▼\n┌─────────────────────────────────────┐\n│  Kubernetes Cluster                 │\n│  ┌──────────┐ ┌──────────────────┐  │\n│  │ CRD:     │ │ Managed:         │  │\n│  │ Valkey   │ │ StatefulSet      │  │\n│  │ Cluster  │ │ Services (2)     │  │\n│  │          │ │ ConfigMap        │  │\n│  │          │ │ Secret           │  │\n│  │          │ │ PDB              │  │\n│  └──────────┘ └──────────────────┘  │\n│  ┌──────────────────────────────┐   │\n│  │ Valkey Pods (master+replicas)│   │\n│  │ Pod-0: master                │   │\n│  │ Pod-1..N: REPLICAOF pod-0   │   │\n│  └──────────────────────────────┘   │\n└─────────────────────────────────────┘\n```\n\n## Quick Start\n\n```bash\n# Build\nlake build gungnir_operator\n\n# Docker\ndocker build -t gungnir-operator:latest .\n\n# Deploy via Helm\nhelm install gungnir charts/gungnir-operator/ -n gungnir-system --create-namespace\n\n# Create a ValkeyCluster\nkubectl apply -f - \u003c\u003cEOF\napiVersion: valkey.verilean.io/v1\nkind: ValkeyCluster\nmetadata:\n  name: my-valkey\n  namespace: valkey-test\nspec:\n  replicas: 3\n  image: \"valkey/valkey:7.2\"\n  port: 6379\nEOF\n```\n\n## Key Features\n\n- **Operator-as-Sentinel**: Integrates Sentinel monitoring directly — no separate Sentinel containers\n- **Formally verified**: TLA-style temporal logic proofs in Lean 4\n- **Pure Lean 4**: No FFI dependencies, pure RESP3 parser\n- **Anvil pattern**: State machine reconciler with one API call per transition\n- **Leader election**: K8s Lease API with expiry detection\n- **Replication**: Automatic master-replica setup via startup script\n\n## Formal Verification\n\nThe operator uses a TLA-style temporal logic framework (`TemporalLogic.lean`) with:\n- `always` (□), `eventually` (◇), `leads_to` (~\u003e), `weak_fairness`\n- Safety invariants proved as inductive invariants over `validTransition`\n- Liveness properties stated as leads-to chains (ESR from Anvil)\n- All proofs discharged — 0 sorry, 4 TCB axioms\n\nSee [plans.md](plans.md) and [features.md](features.md) for full details.\n\n## Author\n\n**Junji Hashimoto**\n* Background: Haskell, Lean 4, Formal Methods, Critical Infrastructure Operations.\n\n---\n*Building the shield for data sovereignty.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverilean%2Fgungnir-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fverilean%2Fgungnir-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverilean%2Fgungnir-operator/lists"}