{ "description": "Verified Soma programs. Every entry passed `soma check` (and `soma test` / `soma verify` where applicable) on the soma version below, re-run when this index was generated. Fetch `url` for the source. Filter by `domain` or `features` to find a working example of what you are about to write.", "soma_version": "3.2.4", "count": 14, "domains": { "devops": 14 }, "features": [ "agent", "cost", "fail", "guard", "http", "invariant", "lambda", "match", "multi_cell", "native", "pipeline", "service", "skeleton", "state_machine", "sum_type", "think", "tools", "try" ], "programs": [ { "id": "devops/backup_retention", "domain": "devops", "title": "BACKUP RETENTION — the floor you cannot prune through", "summary": "BACKUP RETENTION — the floor you cannot prune through On January 31, 2017, a GitLab engineer cleaning up replication lag ran `rm -rf` on what turned out to be the PRIMARY database directory. That was survivable — until all five backup mechanisms turned out to be broken: pg_dump silently producing empty files, S3 uploads failing, snapshots disabled. Six hours of production data were gone forever. Two structural fixes here. First, a backup is only trusted after a restore drill: the lifecycle forces created -> verifying -> verified, and a backup that fails its drill lands in `corrupt`, a TERMINAL state that can never be counted or restored from. Second, the count of verified copies lives behind a memory invariant with a floor of 3: the prune that would leave you with two copies is refused by the MEMORY, not by a retention script somebody edits at 2 a.m.", "url": "https://soma-lang.dev/corpus/devops/backup_retention.cell", "repo_path": "examples/corpus/devops/backup_retention.cell", "lines": 102, "features": [ "state_machine", "invariant", "try" ], "cells": [ "BackupVault", "RetentionTests" ] }, { "id": "devops/blue_green_cutover", "domain": "devops", "title": "BLUE/GREEN CUTOVER — there is no state where nobody serves traffic", "summary": "BLUE/GREEN CUTOVER — there is no state where nobody serves traffic Blue/green deployment's nightmare is the gap: blue is drained, green isn't ready, and for ninety seconds production serves nothing. It is the load-balancer cousin of the airlock problem — two doors that must never both be shut. Salesforce's May 2021 outage had this shape: a DNS change rolled out in a way that briefly left no servers answering, and the tooling needed those very servers to roll back. In this controller the gap is not a state. Every state names exactly which pool is live: blue_live, shifting_to_green (BOTH serve), green_live, shifting_to_blue (BOTH serve). A \"both dark\" state does not exist in the machine, and `soma verify` proves the reachable set is exactly these four. The traffic split is invariant-walled to 0..100 percent, so no weight calculation can send 130% or -30% of traffic anywhere.", "url": "https://soma-lang.dev/corpus/devops/blue_green_cutover.cell", "repo_path": "examples/corpus/devops/blue_green_cutover.cell", "lines": 114, "features": [ "state_machine", "invariant", "try" ], "cells": [ "BlueGreen", "CutoverTests" ] }, { "id": "devops/cert_rotation", "domain": "devops", "title": "CERT ROTATION — expiry is an escalation ladder, not a surprise", "summary": "CERT ROTATION — expiry is an escalation ladder, not a surprise On December 6, 2018, an expired certificate inside Ericsson's SGSN software took mobile data down for 32 million O2 users in the UK and millions more on SoftBank in Japan. In February 2020, Microsoft Teams went down worldwide because an auth certificate simply lapsed. Nobody \"decided\" to let them expire — the deadline just never escalated. This controller makes expiry a one-way ladder the verifier checks: valid -> renewal_due -> critical -> expired, with rotation available at every rung BEFORE the fall. Both endings are TERMINAL — an expired cert can never quietly become valid again, and a superseded cert is retired for good. The lifetime ledger enforces the CA/Browser-forum ceiling: no handler can mint a certificate longer than 398 days.", "url": "https://soma-lang.dev/corpus/devops/cert_rotation.cell", "repo_path": "examples/corpus/devops/cert_rotation.cell", "lines": 108, "features": [ "state_machine", "invariant", "try" ], "cells": [ "CertManager", "CertTests" ] }, { "id": "devops/db_migration", "domain": "devops", "title": "DB MIGRATION — applied migrations are immutable history", "summary": "DB MIGRATION — applied migrations are immutable history Every schema-drift horror story starts the same way: someone edits a migration that already ran in production. Staging replays the edited file, prod keeps the old shape, and three weeks later a column that \"must exist\" doesn't. Flyway and Liquibase bolt on checksum errors; here immutability is the machine itself: `applied` is a TERMINAL state `soma verify` proves you cannot leave. Undoing means writing a NEW down-migration, never rewriting the past. The second wall is the migrator lock — the GitLab-style disaster of two operators running migrations concurrently is refused by a memory invariant that admits at most one lock holder.", "url": "https://soma-lang.dev/corpus/devops/db_migration.cell", "repo_path": "examples/corpus/devops/db_migration.cell", "lines": 104, "features": [ "state_machine", "invariant", "try" ], "cells": [ "Migrator", "MigrationTests" ] }, { "id": "devops/deploy_canary", "domain": "devops", "title": "DEPLOY CANARY — the staged rollout you cannot skip", "summary": "DEPLOY CANARY — the staged rollout you cannot skip On July 19, 2024, CrowdStrike pushed a content update to every Windows sensor on Earth at once. No canary ring, no staged expansion — 8.5 million machines blue-screened, grounding airlines and closing hospitals. The fix that day would have been boring: ship to 1% first. Here \"ship to 1% first\" is not a policy document. The release machine has NO edge from `built` to `expanding` or `complete` — global blast radius without a canary is unrepresentable, and `soma verify` proves it. A rolled-back release is TERMINAL: you cut a new build, you never re-push the one that burned. The canary slice itself is walled by a memory invariant: a \"canary\" taking more than 5% of traffic is rejected at the write.", "url": "https://soma-lang.dev/corpus/devops/deploy_canary.cell", "repo_path": "examples/corpus/devops/deploy_canary.cell", "lines": 102, "features": [ "state_machine", "invariant", "try" ], "cells": [ "DeployPipeline", "PipelineTests" ] }, { "id": "devops/dns_change_control", "domain": "devops", "title": "DNS CHANGE CONTROL — no record goes live without passing validation", "summary": "DNS CHANGE CONTROL — no record goes live without passing validation On October 4, 2021, a routine maintenance command at Facebook withdrew every BGP route to its DNS servers. An audit tool existed precisely to block commands like that — but a bug let the command bypass it. With DNS gone, facebook.com vanished for six hours, internal tools died, and engineers couldn't badge into the datacenter to fix it. The lesson is not \"audit harder\", it is: the bypass must not be a path. In this change pipeline `live` is only reachable through `validated` and `staged` — there is no drafted -> live edge for a buggy tool to take, and `soma verify` proves it. A reverted change is TERMINAL: you draft a new change with a new review, you never re-push the one that broke the internet. TTLs sit behind a memory invariant so no change can ship a record the resolvers would cache for a year.", "url": "https://soma-lang.dev/corpus/devops/dns_change_control.cell", "repo_path": "examples/corpus/devops/dns_change_control.cell", "lines": 102, "features": [ "state_machine", "invariant", "try" ], "cells": [ "DnsChanges", "ChangeGateTests" ] }, { "id": "devops/feature_flag_kill_switch", "domain": "devops", "title": "KILL SWITCH — a dead flag stays dead", "summary": "KILL SWITCH — a dead flag stays dead On August 1, 2012, Knight Capital repurposed an old feature flag — \"Power Peg\", dead code from 2003 — for a new router. One of eight servers still ran the old code. When the recycled flag flipped on, the zombie code woke up and bought $7 billion of stock in 45 minutes. Knight lost $440M and the company. The root cause was not the bug; it was that a KILLED flag could come back to life. Here `killed` is a TERMINAL state — `soma verify` proves no path out. Re-enabling a killed feature means minting a NEW flag through a new review, never resurrecting the old one. The rollout percentage rides a memory invariant so no handler can write an out-of-range exposure.", "url": "https://soma-lang.dev/corpus/devops/feature_flag_kill_switch.cell", "repo_path": "examples/corpus/devops/feature_flag_kill_switch.cell", "lines": 105, "features": [ "state_machine", "invariant", "try" ], "cells": [ "FeatureFlags", "KillSwitchTests" ] }, { "id": "devops/fleet_sync_activation", "domain": "devops", "title": "FLEET SYNC — no activation until every node runs the same code", "summary": "FLEET SYNC — no activation until every node runs the same code The other half of the Knight Capital disaster: a technician deployed the new router to only 7 of 8 servers. The fleet was split-brained — one machine interpreted the activation flag as 2003-era \"Power Peg\" logic. Activating a half-deployed fleet is what turned a deploy slip into $440M of runaway orders. This controller makes the split-brain activation unrepresentable. `activated` is only reachable from `synced`, and the handler that enters `synced` requires the pending-node ledger to read zero. The ledger itself is invariant-walled: it can never go negative (no double-counting a node) and never exceed the fleet size.", "url": "https://soma-lang.dev/corpus/devops/fleet_sync_activation.cell", "repo_path": "examples/corpus/devops/fleet_sync_activation.cell", "lines": 100, "features": [ "state_machine", "invariant", "try" ], "cells": [ "FleetSync", "FleetTests" ] }, { "id": "devops/image_promotion", "domain": "devops", "title": "IMAGE PROMOTION — nothing unscanned, unsigned, or vulnerable ships", "summary": "IMAGE PROMOTION — nothing unscanned, unsigned, or vulnerable ships The SolarWinds breach (disclosed December 2020) worked because the build pipeline itself was the attack surface: malicious code was injected during the build, then SIGNED and shipped to ~18,000 organizations as a legitimate update. Defense afterward converged on one idea — provenance gates: an artifact reaches production only by passing every gate, in order, with no side door. This registry encodes the gates as topology: built -> scanned -> signed -> promoted, and `soma verify` proves there is no edge that skips a gate. An image whose scan finds critical CVEs lands in `quarantined` — TERMINAL, because you rebuild from a patched base, you never \"un-quarantine\". The promoted registry's CVE ledger has a memory invariant pinned at zero: recording a critical vulnerability against a production image is a write the memory itself refuses.", "url": "https://soma-lang.dev/corpus/devops/image_promotion.cell", "repo_path": "examples/corpus/devops/image_promotion.cell", "lines": 105, "features": [ "state_machine", "invariant", "try" ], "cells": [ "ImageRegistry", "ProvenanceTests" ] }, { "id": "devops/incident_ladder", "domain": "devops", "title": "INCIDENT LADDER — severity only climbs, and closure needs a postmortem", "summary": "INCIDENT LADDER — severity only climbs, and closure needs a postmortem Two ways incident processes rot. First, \"sev gaming\": an on-call quietly downgrades a Sev1 to Sev3 so the SLA clock stops and the VP page never fires — the 2013 Target breach unfolded exactly this way, with FireEye alerts dismissed for weeks while card data walked out. Second, closing without learning: the incident is marked resolved, no postmortem happens, and the same outage returns in six months. Both rots are unrepresentable here. Severity is a one-way ladder — there is no de-escalation edge, only mitigation. And `closed` is reachable ONLY through `postmortem_done`: the machine has no edge from mitigated to closed, so \"we'll write it up later\" cannot compile. `soma verify` proves closed is terminal and that every state can still reach it — no incident is ever stuck open forever.", "url": "https://soma-lang.dev/corpus/devops/incident_ladder.cell", "repo_path": "examples/corpus/devops/incident_ladder.cell", "lines": 118, "features": [ "state_machine", "invariant", "try" ], "cells": [ "IncidentDesk", "LadderTests" ] }, { "id": "devops/pager_escalation", "domain": "devops", "title": "PAGER ESCALATION — no page resolves without a human acknowledging it", "summary": "PAGER ESCALATION — no page resolves without a human acknowledging it In the 2013 Target breach, FireEye flagged the malware and fired alerts to the security team — twice. The alerts were reviewed and dismissed without action; 40 million card numbers walked out during the busiest shopping weeks of the year. The killer pattern is the auto-resolve: an alert that nobody acknowledged quietly disappears from the queue, and the system that paged looks healthy again. In this pager, `resolved` is only reachable from `acked` — there is no triggered -> resolved edge for an auto-close to take, and `soma verify` proves it. An unacknowledged page can only ESCALATE: on-call, then secondary, then the manager — a one-way ladder with no edge pointing down. The unanswered-escalation counter is invariant-capped: past three hops the page cannot be re-escalated into the void, it must be acknowledged at the top of the chain.", "url": "https://soma-lang.dev/corpus/devops/pager_escalation.cell", "repo_path": "examples/corpus/devops/pager_escalation.cell", "lines": 110, "features": [ "state_machine", "invariant", "try" ], "cells": [ "Pager", "PagerTests" ] }, { "id": "devops/rate_limiter", "domain": "devops", "title": "RATE LIMITER — admission control with a quota the memory enforces", "summary": "RATE LIMITER — admission control with a quota the memory enforces On September 20, 2015, DynamoDB's storage servers all renewed their metadata leases at once after a network blip. The metadata service had no effective admission control; the retry storm starved it, which caused more timeouts, which caused more retries. The brownout took down large parts of us-east-1 for five hours and dragged twenty other AWS services with it. Cascading retry storms are what rate limiters exist to stop — IF the limiter itself cannot be talked out of its quota. This limiter's token bucket lives behind a memory invariant: tokens can never go below zero (no overdraft \"just this once\") and never above the burst ceiling (no refill bug minting infinite capacity). The breaker is a state machine with a one-way path through `shedding` and `recovering` — there is no edge from shedding straight back to closed-and-full-traffic, so the thundering herd cannot re-arrive at once.", "url": "https://soma-lang.dev/corpus/devops/rate_limiter.cell", "repo_path": "examples/corpus/devops/rate_limiter.cell", "lines": 119, "features": [ "state_machine", "invariant", "try" ], "cells": [ "RateLimiter", "LimiterTests" ] }, { "id": "devops/secret_rotation", "domain": "devops", "title": "SECRET ROTATION — a revoked credential never logs in again", "summary": "SECRET ROTATION — a revoked credential never logs in again In 2016, attackers found Uber's AWS keys sitting in a private GitHub repo. The keys were long-lived — never rotated — and unlocked data on 57 million riders and drivers. The pattern repeats everywhere: a credential leaks, someone \"disables\" it in a dashboard, and months later a recovery script or a confused admin re-enables it. Here the credential lifecycle is a machine where `revoked` and `retired` are TERMINAL — `soma verify` proves no handler, script, or 3 a.m. admin can resurrect a dead key. Authentication consults the machine, so a revoked key fails closed. Key age sits behind a memory invariant: a credential older than the 90-day rotation policy cannot even be recorded, which makes \"we forgot to rotate\" a write error.", "url": "https://soma-lang.dev/corpus/devops/secret_rotation.cell", "repo_path": "examples/corpus/devops/secret_rotation.cell", "lines": 115, "features": [ "state_machine", "invariant", "try" ], "cells": [ "SecretVault", "VaultTests" ] }, { "id": "devops/state_lock", "domain": "devops", "title": "STATE LOCK — two concurrent applies can never both hold the lock", "summary": "STATE LOCK — two concurrent applies can never both hold the lock Terraform's docs put it bluntly: two `apply` runs against the same state file at once will corrupt it. Teams learn this the hard way — CI kicks off a plan while an engineer applies from a laptop, the state JSON is half-written by both, and suddenly Terraform wants to destroy and recreate half of production. HashiCorp added state locking for exactly this; here the lock's mutual exclusion is a proof, not a DynamoDB conditional write you hope is configured. The lock is a state machine: `unlocked -> held -> unlocked`, with a `stale` branch for the crashed-runner case — force-unlock exists, but ONLY from `stale`, never as a shortcut around a live holder. The holder-count ledger is invariant-walled at 0..1: a second holder is a write the memory refuses, independent of the machine.", "url": "https://soma-lang.dev/corpus/devops/state_lock.cell", "repo_path": "examples/corpus/devops/state_lock.cell", "lines": 114, "features": [ "state_machine", "invariant", "try" ], "cells": [ "StateLock", "MutexTests" ] } ] }