{ "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": 15, "domains": { "energy": 15 }, "features": [ "agent", "cost", "fail", "guard", "http", "invariant", "lambda", "match", "multi_cell", "native", "pipeline", "service", "skeleton", "state_machine", "sum_type", "think", "tools", "try" ], "programs": [ { "id": "energy/anti_islanding", "domain": "energy", "title": "ANTI-ISLANDING — a solar inverter must never energize a \"dead\" line", "summary": "ANTI-ISLANDING — a solar inverter must never energize a \"dead\" line When a feeder breaker opens, every lineworker on that circuit treats the wire as dead. But a neighborhood of rooftop solar can keep the islanded segment energized — backfeeding lethal voltage into a line the crew has every reason to believe is isolated. This is why IEEE 1547 mandates that a grid-tied inverter CEASE energizing within 2 seconds of grid loss and stay off until the grid has been stable for a full hold-off window (classically 5 minutes) — not \"until the voltage flickers back\". The lethal shortcut is `ceased -> exporting`: the grid blinks, the inverter jumps straight back to full output while a recloser is mid- sequence or a crew is mid-repair. Below, that transition DOES NOT EXIST. The only exit from `ceased` is `monitoring`, where the hold-off clock restarts. soma verify proves the reachable graph; the export-watts slot is a second wall — output is zeroed on cessation and capped at nameplate.", "url": "https://soma-lang.dev/corpus/energy/anti_islanding.cell", "repo_path": "examples/corpus/energy/anti_islanding.cell", "lines": 107, "features": [ "state_machine", "invariant", "try" ], "cells": [ "Inverter", "IslandTests" ] }, { "id": "energy/battery_soc", "domain": "energy", "title": "BATTERY DISPATCH — the charge window is a wall, not a setpoint", "summary": "BATTERY DISPATCH — the charge window is a wall, not a setpoint April 19, 2019, Surprise, Arizona: a rack at the APS McMicken battery facility went into thermal runaway; when firefighters opened the door the accumulated gases exploded and put four of them in the hospital. Lithium cells driven outside their charge window — overcharged at the top, or dragged below empty by an aggressive arbitrage optimizer — plate lithium, grow dendrites, and eventually burn. Dispatch software optimizes revenue and will happily command one more charging interval at the top of the window unless something refuses. Here the refusal is the memory itself: state-of-charge lives in a slot whose invariant is 0..100. The write that would cross the bound is rejected BY THE SLOT, even if every guard in the handler is deleted. A 20%-per-interval ramp limit rides on top in the handler.", "url": "https://soma-lang.dev/corpus/energy/battery_soc.cell", "repo_path": "examples/corpus/energy/battery_soc.cell", "lines": 83, "features": [ "invariant", "try" ], "cells": [ "Battery", "SocTests" ] }, { "id": "energy/black_start", "domain": "energy", "title": "BLACK START — you cannot boot a power plant from a dead grid out of order", "summary": "BLACK START — you cannot boot a power plant from a dead grid out of order August 14, 2003: the Northeast blackout dropped 61,800 MW and 50 million people. Restoration took days, because a big thermal plant cannot start itself — its boiler feed pumps, fans, and lube-oil systems need tens of megawatts of \"station service\" power that normally comes FROM the grid. In February 2021, winter storm Uri brought ERCOT within minutes of a total collapse that engineers estimated would have taken weeks to black-start. The restoration sequence is rigid for physical reasons: a small self-starting unit (hydro, diesel) cranks first; it feeds the big plant's auxiliaries; only then can the big unit roll; the unit then carries a small stable island; and the island is synchronized to its neighbors LAST. Skip a step and you trip everything back to black. The sequence below is the state machine. Every skip is a transition that does not exist; collapse paths return to `blackout`; and `reconnected` is terminal for the event — the restoration log of a finished black start is history. soma verify proves all of it.", "url": "https://soma-lang.dev/corpus/energy/black_start.cell", "repo_path": "examples/corpus/energy/black_start.cell", "lines": 118, "features": [ "state_machine", "invariant", "try" ], "cells": [ "BlackStart", "BlackStartTests" ] }, { "id": "energy/breaker_reclose", "domain": "energy", "title": "RECLOSER — a trip is permanent until a human walks the line", "summary": "RECLOSER — a trip is permanent until a human walks the line A distribution recloser that trips on a fault will, by default, try to re-energize the line a few seconds later — most faults are a branch brushing a phase and clear themselves. But a conductor lying on the ground is the OTHER kind of fault: every reclose attempt pumps thousands of amps into whatever the wire is touching — a dry field, a car, a person. Reclosing into downed lines has electrocuted bystanders and started wildfires; after 2020, utilities in California fire country (PG&E's \"fast trip\" program) disabled automatic reclosing outright. Here the rule is structural, not procedural: from `tripped` the ONLY exit is `patrolling` — a crew dispatched to walk the span. `closed` is reachable from `tripped` by no path that skips the patrol, and a line the patrol condemns can never be energized again: `condemned` is terminal, and `soma verify` proves it.", "url": "https://soma-lang.dev/corpus/energy/breaker_reclose.cell", "repo_path": "examples/corpus/energy/breaker_reclose.cell", "lines": 94, "features": [ "state_machine", "invariant", "try" ], "cells": [ "Recloser", "RecloseTests" ] }, { "id": "energy/demand_response", "domain": "energy", "title": "DEMAND RESPONSE — no payment before measurement, and settlement is final", "summary": "DEMAND RESPONSE — no payment before measurement, and settlement is final Demand-response programs pay customers for NOT consuming during a grid emergency — which makes the payout an invitation to invent curtailment. In 2013 FERC penalized Rumford Paper Co. for gaming its DR baseline: the mill ran flat-out during the baseline window, then \"curtailed\" to its normal level and collected for megawatts it never actually shed. The money leaks wherever settlement can run before measurement, or run twice. Here the event lifecycle is the control: payout can only be posted from `measured` (verified meter data in hand), `settled` is TERMINAL — no re-settlement, no retroactive sweetener — and a cancelled event is terminal too, payable by no path. soma verify proves both. The payout ledger refuses negative or program-cap-busting amounts at the memory.", "url": "https://soma-lang.dev/corpus/energy/demand_response.cell", "repo_path": "examples/corpus/energy/demand_response.cell", "lines": 124, "features": [ "state_machine", "invariant", "try" ], "cells": [ "DrEvent", "DrTests" ] }, { "id": "energy/ev_charging", "domain": "energy", "title": "EV CHARGING — no current before the handshake, no session past the cap", "summary": "EV CHARGING — no current before the handshake, no session past the cap Two real failure modes, one charging post. 1. Current before negotiation. The J1772/CCS pilot handshake exists so the cable, the car, and the post agree on a current the weakest link can carry. Skip it — a bent pin, a counterfeit adapter — and a 16 A cable carries 48 A until the insulation melts. Garage fires from uncertified EVSE gear are a documented pattern. 2. Charging past the cell limit. GM's 2021 recall of every Chevy Bolt came down to defective cells that became dangerous near full charge; the interim fix was SOFTWARE: cap the session. A cap that lives in an if-statement is a cap a firmware update can delete. Both are structural here: `charging` is reachable ONLY through `authorized` (the handshake state — soma verify proves it), and the session energy ledger refuses any write past 60 kWh at the memory.", "url": "https://soma-lang.dev/corpus/energy/ev_charging.cell", "repo_path": "examples/corpus/energy/ev_charging.cell", "lines": 124, "features": [ "state_machine", "invariant", "try" ], "cells": [ "ChargePost", "ChargeTests" ] }, { "id": "energy/gas_purge", "domain": "energy", "title": "GAS TURBINE LIGHT-OFF — purge before every ignition attempt, no exceptions", "summary": "GAS TURBINE LIGHT-OFF — purge before every ignition attempt, no exceptions February 7, 2010, Middletown, Connecticut: the Kleen Energy power plant, weeks from commissioning, exploded during a natural-gas pipe-cleaning operation. Six workers died. The blast led NFPA 56 to ban flammable-gas blows outright — but the same physics lives inside every gas turbine and HRSG: admit fuel without flame, and the exhaust path fills with a combustible cloud waiting for one spark. That is why NFPA 85 requires a forced-air purge of several full volume changes before EVERY ignition attempt — including the retry after a failed light-off, which is exactly when an impatient operator (or a buggy auto-restart) wants to skip it. Here the purge is unskippable: `firing` is reachable only from `purge_complete`, and the ONLY exit from `failed_light` is back into `purging`. soma verify proves no path admits fuel into an unpurged machine. The purge-volume ledger refuses credit for less than the mandated 5 volume changes.", "url": "https://soma-lang.dev/corpus/energy/gas_purge.cell", "repo_path": "examples/corpus/energy/gas_purge.cell", "lines": 134, "features": [ "state_machine", "invariant", "try" ], "cells": [ "Combustor", "PurgeTests" ] }, { "id": "energy/generator_sync", "domain": "energy", "title": "GENERATOR PARALLELING — sync-check before the breaker, always", "summary": "GENERATOR PARALLELING — sync-check before the breaker, always Closing a generator breaker onto a live grid while the machine is out of phase is one of the most violent things you can do to rotating iron. At 120 degrees out, the instantaneous torque on the shaft is several times rated — enough to twist couplings, crack stator end-windings, and scrap a turbine-generator worth more than the plant's annual revenue. This is why every utility interconnection requires a sync-check relay (ANSI device 25): slip, phase angle, and voltage must all be inside the window BEFORE the close command can reach the breaker. Here the relay is the state machine: `online` is reachable ONLY from `synchronized`. From `at_speed` (machine at rated speed and voltage, breaker open) there is no close path — the transition does not exist, so no operator shortcut, race, or script can close out of phase. when online, and never beyond the 500 MW nameplate.", "url": "https://soma-lang.dev/corpus/energy/generator_sync.cell", "repo_path": "examples/corpus/energy/generator_sync.cell", "lines": 137, "features": [ "state_machine", "invariant", "try" ], "cells": [ "Genset", "SyncTests" ], "usage": [ "soma verify proves it. The MW slot is the second wall: load only flows" ] }, { "id": "energy/load_shedding", "domain": "energy", "title": "LOAD SHEDDING — the transformer's nameplate is a wall, hospitals shed last", "summary": "LOAD SHEDDING — the transformer's nameplate is a wall, hospitals shed last When demand outruns supply, somebody's lights go off — the only question is whose, and whether the choice is made by a priority plan or by a melting transformer. In February 2021, winter storm Uri forced ERCOT to shed 20,000 MW; where rotation plans failed, circuits feeding hospitals and water plants went dark alongside empty offices, and people died of cold. The two properties a shedding controller must keep: 1. The transformer NEVER carries more than nameplate. Here that is a memory invariant — connecting a feeder that would overload the bank is rejected at the write, not by an if-statement upstream. 2. Shedding follows priority: interruptible contracts (3) drop before commercial (2); critical loads (1 — hospitals, water) are never auto-shed. The shed handler structurally cannot pick a priority-1 feeder.", "url": "https://soma-lang.dev/corpus/energy/load_shedding.cell", "repo_path": "examples/corpus/energy/load_shedding.cell", "lines": 112, "features": [ "invariant", "try" ], "cells": [ "Shedder", "ShedTests" ] }, { "id": "energy/meter_billing", "domain": "energy", "title": "METER BILLING — you are billed exactly what the meter read, once", "summary": "METER BILLING — you are billed exactly what the meter read, once In December 2015 the UK regulator Ofgem fined npower £26 million for billing failures: estimated and duplicated invoices that didn't match what meters had recorded, sent to half a million customers. The root pattern is always the same — billing reads a copy of the meter data that can drift, and nothing structural ties the invoice to the register. Here conservation is by construction. Each billing cycle is a state machine: usage accumulates only while `accumulating`; `locked` snapshots the register; the ONLY write to `billed` copies the metered value at invoice time. You cannot invoice an unlocked register (the transition doesn't exist), cannot invoice twice (invoiced -> invoiced doesn't exist), and a settled cycle is TERMINAL — no retroactive \"adjustment\".", "url": "https://soma-lang.dev/corpus/energy/meter_billing.cell", "repo_path": "examples/corpus/energy/meter_billing.cell", "lines": 115, "features": [ "state_machine", "invariant", "match", "try" ], "cells": [ "Billing", "BillingTests" ], "usage": [ "soma verify proves the lifecycle; the audit signal pins billed==metered." ] }, { "id": "energy/spillway_gates", "domain": "energy", "title": "SPILLWAY GATES — a dam may never lose its last release path", "summary": "SPILLWAY GATES — a dam may never lose its last release path February 2017, Oroville, California: the tallest dam in the US lost its main spillway to erosion mid-flood, the emergency spillway began to fail within hours of first use, and 188,000 people downstream were evacuated. The lesson generalized by every dam-safety review since: release capacity is life-safety equipment, and maintenance scheduling is where it silently disappears — gate 3 is down for seal replacement, gate 5's hoist motor is out, a contractor asks to isolate gate 7 \"just for the afternoon\", and suddenly the dam cannot pass the inflow it was built for. Two structural walls below. The fleet ledger `gates_avail` carries an invariant floor of ONE: the write that would take the last operable gate out of service is rejected by the memory, whatever the work order says. And each gate's overhaul is a state machine: an overhauled gate returns to service only through `wet_tested` — an untested gate back on the flood roster is a transition that does not exist. soma verify proves it.", "url": "https://soma-lang.dev/corpus/energy/spillway_gates.cell", "repo_path": "examples/corpus/energy/spillway_gates.cell", "lines": 121, "features": [ "state_machine", "invariant", "try" ], "cells": [ "Spillway", "SpillwayTests" ] }, { "id": "energy/spinning_reserve", "domain": "energy", "title": "SPINNING RESERVE — every megawatt you sell must claim real iron", "summary": "SPINNING RESERVE — every megawatt you sell must claim real iron Spinning reserve is capacity a generator is PAID to hold back, ready to inject within minutes when a unit elsewhere trips. The market failure: energy and reserve are sold in separate transactions, so a 500 MW unit can dispatch 450 MW of energy AND sell 100 MW of reserve — 550 MW of promises against 500 MW of iron. During winter storm Uri in February 2021, ERCOT discovered how much of its purchased reserve was paper: units that had sold readiness tripped offline or never ramped, and the shortfall became rolling blackouts in single-digit cold. The fix here is one slot: `claimed` holds energy dispatch PLUS reserve commitments per unit, and its invariant is the nameplate. Both markets write through the same wall, so the double-sell is rejected at the memory — there is no code path on which promises exceed iron.", "url": "https://soma-lang.dev/corpus/energy/spinning_reserve.cell", "repo_path": "examples/corpus/energy/spinning_reserve.cell", "lines": 109, "features": [ "invariant", "try" ], "cells": [ "ReserveDesk", "ReserveTests" ] }, { "id": "energy/substation_loto", "domain": "energy", "title": "LOCKOUT-TAGOUT — test before touch, and nobody re-energizes over a lock", "summary": "LOCKOUT-TAGOUT — test before touch, and nobody re-energizes over a lock Electrical workers are killed every year by circuits that were \"locked out\": a breaker opened but the bus still live through a backfeed, an induced voltage from the parallel line nobody tested for, or a dispatcher closing remotely while a crew is on the conductors. OSHA's hazardous- energy rules (1910.147 / 1910.269) exist because each of these has a body count. The two rules that do the saving: TEST BEFORE TOUCH — isolation is not proof. You meter every phase before grounds go on. Here, `grounded` is unreachable from `isolated` without passing `proven_dead`; soma verify proves it. ONE LOCK, ONE LIFE — every worker hangs a personal lock; the line cannot be declared clear while ANY lock remains. The lock ledger refuses to go negative (you cannot remove a lock that isn't yours to remove), and re-energizing from `grounded` is not a transition at all.", "url": "https://soma-lang.dev/corpus/energy/substation_loto.cell", "repo_path": "examples/corpus/energy/substation_loto.cell", "lines": 137, "features": [ "state_machine", "invariant", "try" ], "cells": [ "Loto", "LotoTests" ] }, { "id": "energy/transformer_overload", "domain": "energy", "title": "TRANSFORMER EMERGENCY LOADING — overload only with every fan running", "summary": "TRANSFORMER EMERGENCY LOADING — overload only with every fan running A large power transformer dies slowly and then suddenly: every hour spent above its thermal rating cooks the paper insulation (IEEE C57.91 calls it loss-of-life), until one hot afternoon the winding faults and forty tons of mineral oil have an ignition source. Grid operators DO run transformers past nameplate during emergencies — that is what the ONAF cooling stages are for: first fan bank buys you 115%, second bank 125%, but only while the fans are actually spinning. The classic failure is the quiet one: a fan contactor died months ago, the SCADA point was never wired, and the bank takes emergency load with cooling it does not have. Here the cooling stage is a state machine and the loading ceiling is derived FROM the state: `emergency_load` is a state reachable only from `fans_full` — soma verify proves overload cannot be entered with idle fans. The MVA slot's invariant is the absolute thermal wall at 125.", "url": "https://soma-lang.dev/corpus/energy/transformer_overload.cell", "repo_path": "examples/corpus/energy/transformer_overload.cell", "lines": 134, "features": [ "state_machine", "invariant", "try" ], "cells": [ "Transformer", "OverloadTests" ] }, { "id": "energy/wind_overspeed", "domain": "energy", "title": "WIND TURBINE OVERSPEED — after an emergency brake, inspection or nothing", "summary": "WIND TURBINE OVERSPEED — after an emergency brake, inspection or nothing February 22, 2008, Hornslet, Denmark: a 600 kW turbine's brakes failed during a storm and the machine spun until it tore itself apart — blades and nacelle thrown hundreds of meters, the disintegration caught on a video that every wind technician has since been shown. A rotor past its design speed stores energy in exactly the form that kills: blade root fatigue you cannot see from the ground. That is why an overspeed event is never \"reset and resume\". Here the rule is the machine: from `storm_brake` the ONLY exit is `inspection` — there is no path back to `running` that skips a human at the blade roots. A turbine the inspection condemns is `condemned`, terminal, forever; soma verify proves both. The rotor-speed slot is the inner wall: no write can record an rpm past the 25-rpm design limit, so the telemetry layer cannot even pretend an overspeed was normal.", "url": "https://soma-lang.dev/corpus/energy/wind_overspeed.cell", "repo_path": "examples/corpus/energy/wind_overspeed.cell", "lines": 136, "features": [ "state_machine", "invariant", "try" ], "cells": [ "Turbine", "OverspeedTests" ] } ] }