{"id":21470499,"url":"https://github.com/manifoldfinance/tla-spec","last_synced_at":"2026-03-19T20:31:51.877Z","repository":{"id":53088616,"uuid":"341091301","full_name":"manifoldfinance/tla-spec","owner":"manifoldfinance","description":"tla++ proofs and verifications","archived":false,"fork":false,"pushed_at":"2021-08-20T08:55:51.000Z","size":4010,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-15T17:03:32.918Z","etag":null,"topics":["distributed","fault-tolerance","pcal","tla","tlaplus"],"latest_commit_sha":null,"homepage":"","language":"TLA","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/manifoldfinance.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}},"created_at":"2021-02-22T05:37:05.000Z","updated_at":"2025-02-16T17:28:55.000Z","dependencies_parsed_at":"2022-09-12T12:21:52.299Z","dependency_job_id":null,"html_url":"https://github.com/manifoldfinance/tla-spec","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/manifoldfinance/tla-spec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manifoldfinance%2Ftla-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manifoldfinance%2Ftla-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manifoldfinance%2Ftla-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manifoldfinance%2Ftla-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/manifoldfinance","download_url":"https://codeload.github.com/manifoldfinance/tla-spec/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manifoldfinance%2Ftla-spec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29054688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T15:43:47.601Z","status":"ssl_error","status_checked_at":"2026-02-03T15:43:46.709Z","response_time":96,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["distributed","fault-tolerance","pcal","tla","tlaplus"],"created_at":"2024-11-23T09:28:00.177Z","updated_at":"2026-02-03T19:32:20.819Z","avatar_url":"https://github.com/manifoldfinance.png","language":"TLA","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# [tla++ specification](#)\n\n\u003e All models are wrong, some are useful, and not having any models is worse than wrong.\n\n\u003c/div\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\n## Conformance Monitoring with TLA+\n\nDistributed systems like µONOS can be difficult to design and even harder to implement. When\nsystems don't strictly conform to their intended properties, unpredictable behaviors can emerge.\nEven with good design and coding practices in place, building confidence in a distributed system\ncan require extensive testing and evaluation.\n\nTo aid in the identification of concurrency bugs and help build confidence that can service and ensure we adhere\nto the formal specifications. Manifold Finance also supports a special form of monitoring designed to detect violations\nof the system's properties. _Conformance monitoring_ in µONOS uses formal modelling techniques to\nspecify and verify system properties in near-real time.\n\n## Deployment\n\nWhen performance conformance monitoring on a production cluster, users must use [Helm] to deploy a\nsingle monitor pod per [TLA+] specification.\n\n### Prerequisites\n\nThe conformance monitor currently requires Kafka to stream traces to TLC.\n\nTo deploy Kafka using Helm, first add the incubator repository to your Helm configuration:\n\n```bash\n$ helm repo add incubator http://storage.googleapis.com/kubernetes-charts-incubator\n```\n\nDefine a `values.yaml` file for the Kafka cluster, configuring the topics to be used by the conformance monitor\nto consume traces and produce alerts:\n\n```yaml\nreplicas: 1\nzookeeper:\n  replicaCount: 1\ntopics:\n  - name: traces\n    partitions: 3\n    replicationFactor: 1\n  - name: alerts\n    partitions: 1\n    replicationFactor: 1\n```\n\nThen, install the `incubator/kafka` chart with the desired configuration overrides:\n\n```bash\n$ helm install kafka incubator/kafka --values values.yaml\n```\n\nThe successful completion of the `kafka-config` pod indicates the Kafka brokers have completed startup and\nconfigured topics have been created.\n\n### Installation\n\nOnce the Kafka cluster has been configured, this chart can be deployed to perform near real-time conformance\nmonitoring on Kafka streams. The monitor uses [TLA+] specifications to evaluate traces received from Kafka,\nand invariants specified in the chart configuration can detect safety violations in the trace stream.\n\nSeveral artifacts are required to by the chart:\n\n* `model` - the name of the module to evaluate\n* `modules` - an array of TLA+ module files to mount to the monitor pod\n* `spec` - the specification to evaluate\n* `init` - the state initialization predicate (required if `spec` is not configured)\n* `next` - the next state relation (required if `spec` is not configured)\n\nAdditional options can be used to specify invariants and other constraints on the model checker:\n\n* `invariants` - an array of invariants to check for each trace\n* `constants` - a mapping of constant values to assign to the model\n* `constraints` - an array of state constraints\n* `properties` - an array of model properties\n\n```bash\n$ helm install my-monitor --set modules={Cache.tla,CacheHistory.tla} --set model=Cache.tla --set config.spec=Spec --set config.invariants={TypeOK}\n```\n\n## Specifications\n\nThe role of the conformance monitor is to track the system state over time and detect violations\nof safety guarantees by analyzing the system state. To do so, [TLA+] specifications are used to\nprovide a formal model for state transitions and specify the invariants to which the system must\nconform.\n\nTLA+ specifications consist of one or more modules defined in `.tla` files. A module defines a set\nof formulas for evaluating the state of the system. The specification provides a formula describing\nthe initial system state and its transitions:\n\n```tla\n---------------------------- MODULE MonotonicTrace --------------------------\n\nEXTENDS Naturals, Sequences\n\n\\* A list of variables in the spec\nvars == \u003c\u003c...\u003e\u003e\n\n\\* The init predicate describing the initial state of the system\nInit == ...\n\n\\* The next state relation describing possible state transitions\nNext == ...\n\n\\* The system specification describes the initial system state and next state relations\nSpec == Init /\\ [][Next]_\u003c\u003cvars\u003e\u003e\n\n=============================================================================\n```\n\nTypically, the TLA+ model checker, TLC, computes and evaluates every state that can be reached\nby the spec according to its initial state and next state relation. Conformance monitoring specs\noperate on an infinite stream of traces, using the `NextTrace` operator to consume and check\ntraces in near-real time:\n\n```tla\nINSTANCE Traces\n\n\\* The previous trace version\nVARIABLE prevVersion\n\n\\* The current trace version\nVARIABLE nextVersion\n\n\\* A list of variables in the spec\nvars == \u003c\u003cprevVersion, nextVersion\u003e\u003e\n\n\\* Read a trace record from the stream and update the previous and next versions\nRead ==\n    LET record == NextTrace\n    IN\n       /\\ PrintT(record)\n       /\\ prevVersion' = nextVersion\n       /\\ nextVersion' = record.version\n\n\\* The init predicate describing the initial state of the system\nInit ==\n    /\\ prevVersion = 0\n    /\\ nextVersion = 0\n\n\\* The next state relation describing possible state transitions\nNext ==\n    \\/ Read\n    \\/ UNCHANGED \u003c\u003cvars\u003e\u003e\n```\n\nThe final component of a conformance spec is the invariant(s). Invariants are predicates\nthat describe the properties of a well behaved (conforming) system. After each trace is\nconsumed and processed from the traces stream, TLC will evaluate invariants to determine\nwhether the system's state conforms to its safety properties:\n\n```tla\n\\* An invariant verifying that the trace version is monotonically increasing\nTypeOK == nextVersion # 0 =\u003e nextVersion \u003c prevVersion\n```\n\nIn the event the invariant is violated by the system traces, the `PublishAlert` operator\ncan be used to publish an alert.\n\n```tla\nINSTANCE Alerts\n\n\\* An invariant verifying that the trace version is monotonically increasing\nTypeOK ==\n    \\/ nextVersion # 0 =\u003e nextVersion \u003c prevVersion\n    \\/ PublishAlert([msg         |-\u003e \"Invariant violated\",\n                     prevVersion |-\u003e prevVersion,\n                     nextVersion |-\u003e nextVersion])\n```\n\nWith the initial state predicate, the next state relation, and the type invariants,\na complete conformance monitoring spec can be compiled:\n\n```tla\n---------------------------- MODULE MonotonicTrace --------------------------\n\nEXTENDS Naturals, Sequences\n\nINSTANCE Traces\n\nINSTANCE Alerts\n\n\\* The previous trace version\nVARIABLE prevVersion\n\n\\* The current trace version\nVARIABLE nextVersion\n\n\\* A list of variables in the spec\nvars == \u003c\u003cprevVersion, nextVersion\u003e\u003e\n\n\\* An invariant verifying that the trace version is monotonically increasing\nTypeOK ==\n    \\/ nextVersion # 0 =\u003e nextVersion \u003c prevVersion\n    \\/ PublishAlert([msg         |-\u003e \"Invariant violated\",\n                     prevVersion |-\u003e prevVersion,\n                     nextVersion |-\u003e nextVersion])\n\n\\* Read a trace record from the traces stream and update the previous and next versions\nRead ==\n    LET record == NextTrace\n    IN\n       /\\ PrintT(record)\n       /\\ prevVersion' = nextVersion\n       /\\ nextVersion' = record.version\n\n\\* The init predicate describing the initial state of the system\nInit ==\n    /\\ prevVersion = 0\n    /\\ nextVersion = 0\n\n\\* The next state relation describing possible state transitions\nNext ==\n    \\/ Read\n    \\/ UNCHANGED \u003c\u003cvars\u003e\u003e\n\n\\* The system specification describes the initial system state and next state relations\nSpec == Init /\\ [][Next]_\u003c\u003cvars\u003e\u003e\n\n=============================================================================\n```\n\n## example Rules \n\nIf Condition is false or null, then: \u003cbr\u003e\nMTF “passes” validation [by default] for Rule. \u003cbr\u003e\nIf Condition is true [by assessment or by default], then: \u003cbr\u003e\nIf Statement is true, MTF “passes” validation for Rule. \u003cbr\u003e\nIf Statement is null, MTF “passes” validation [by default] for Rule. \u003cbr\u003e\nIf Statement is false, MTF “fails” validation for Rule. \u003cbr\u003e\n\n\n## overview \n\n```js\n// TODO\n```\n\n## links\n\n### azure CosmosDB\n[https://github.com/Azure/azure-cosmos-tla](https://github.com/Azure/azure-cosmos-tla)\n\n### tencent WeChat PaxosStore\n[https://github.com/Starydark/PaxosStore-tla](https://github.com/Starydark/PaxosStore-tla)\n\n### elasticsearch - Formal Models for Elasticsearch algorithms\n\n[https://github.com/elastic/elasticsearch-formal-models](https://github.com/elastic/elasticsearch-formal-models)\n\n\n## motivations\n\n\u003e a.k.a blame game\n\n### Failing health checks: Buildkite\n[https://buildkite.com/blog/outage-post-mortem-for-august-22nd](https://buildkite.com/blog/outage-post-mortem-for-august-22nd)\n\n\n## license \n\nGPL-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanifoldfinance%2Ftla-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmanifoldfinance%2Ftla-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanifoldfinance%2Ftla-spec/lists"}