{
 "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": 17,
 "domains": {
  "agents": 17
 },
 "features": [
  "agent",
  "cost",
  "fail",
  "guard",
  "http",
  "invariant",
  "lambda",
  "match",
  "multi_cell",
  "native",
  "pipeline",
  "service",
  "skeleton",
  "state_machine",
  "sum_type",
  "think",
  "tools",
  "try"
 ],
 "programs": [
  {
   "id": "agents/approval_gate",
   "domain": "agents",
   "title": "Human-in-the-loop approval gate guarding an irreversible action",
   "summary": "Human-in-the-loop approval gate guarding an irreversible action. Demonstrates: approve() as a lifecycle gate, a state machine where the \"executing\" path is only reachable past the gate, and a rejected path that lands in a distinct terminal. approve() never answers on its own: a test scripts it with `mock approve true|false`; `soma run` asks the person at the terminal; under `soma serve` (nobody attached) it raises kind \"approval_required\" unless SOMA_APPROVE=always|never states an explicit policy. Run: soma run approval_gate.cell deploy \"v2.1.0\" (asks y/N) SOMA_APPROVE=never soma run approval_gate.cell deploy \"v2.1.0\" Test: soma test approval_gate.cell",
   "url": "https://soma-lang.dev/corpus/agents/approval_gate.cell",
   "repo_path": "examples/corpus/agents/approval_gate.cell",
   "lines": 70,
   "features": [
    "state_machine",
    "agent"
   ],
   "cells": [
    "Deployer",
    "DeployTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/bounded_retry",
   "domain": "agents",
   "title": "Bounded-retry agent — the verified-termination poster child",
   "summary": "Bounded-retry agent — the verified-termination poster child. A naive `failed -> working` retry arrow creates a livelock the model checker would reject. Here the retry COUNT lives in memory and the loop is bounded, so the machine always reaches succeeded or exhausted. Run: SOMA_LLM_MOCK=echo soma run bounded_retry.cell --signal attempt \"flaky-op\" 2 Test: SOMA_LLM_MOCK=echo soma test bounded_retry.cell",
   "url": "https://soma-lang.dev/corpus/agents/bounded_retry.cell",
   "repo_path": "examples/corpus/agents/bounded_retry.cell",
   "lines": 60,
   "features": [
    "state_machine",
    "agent"
   ],
   "cells": [
    "Retrier",
    "RetryTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/budget_guard",
   "domain": "agents",
   "title": "Token-budget enforcement, made testable",
   "summary": "Token-budget enforcement, made testable. Demonstrates: set_budget() as a hard cap, tokens_used()/tokens_remaining(), and a bounded think-loop that STOPS when the budget is exhausted — the verified-termination angle. No network: SOMA_LLM_MOCK=echo. Run: SOMA_LLM_MOCK=echo soma run budget_guard.cell --signal summarize \"a b c d\" Test: SOMA_LLM_MOCK=echo soma test budget_guard.cell",
   "url": "https://soma-lang.dev/corpus/agents/budget_guard.cell",
   "repo_path": "examples/corpus/agents/budget_guard.cell",
   "lines": 52,
   "features": [
    "state_machine",
    "agent",
    "think",
    "try"
   ],
   "cells": [
    "Summarizer",
    "BudgetTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/guarded_agent",
   "domain": "agents",
   "title": "Agent with preconditions and a memory invariant — refuses bad input",
   "summary": "Agent with preconditions and a memory invariant — refuses bad input. Demonstrates: `require ... else` guards on a handler, a memory invariant that rejects out-of-range writes, and assert_fails proving the negative paths actually raise. The agent never enters its work state on bad input. Run: SOMA_LLM_MOCK=echo soma run guarded_agent.cell --signal spend \"rent\" 50 Test: SOMA_LLM_MOCK=echo soma test guarded_agent.cell",
   "url": "https://soma-lang.dev/corpus/agents/guarded_agent.cell",
   "repo_path": "examples/corpus/agents/guarded_agent.cell",
   "lines": 59,
   "features": [
    "state_machine",
    "invariant",
    "agent",
    "fail"
   ],
   "cells": [
    "Treasurer",
    "TreasurerTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/horde_audit",
   "domain": "agents",
   "title": "A horde: one [task] agent per document, a bounded pool, a hard token budget, each verdict stored exactly once, a summary at the end",
   "summary": "A horde: one [task] agent per document, a bounded pool, a hard token budget, each verdict stored exactly once, a summary at the end. Demonstrates: horde(), on_result / on_error / on_done, budget_tokens, horde_status, an [immutable] result slot (a second write would raise). Serve: SOMA_LLM_MOCK=echo SOMA_LLM_MOCK_LATENCY_MS=1000 soma serve horde_audit.cell POST /audit {\"n\": 2000} then GET /progress (and /__soma/ for the dashboard) Test: SOMA_LLM_MOCK=echo soma test horde_audit.cell",
   "url": "https://soma-lang.dev/corpus/agents/horde_audit.cell",
   "repo_path": "examples/corpus/agents/horde_audit.cell",
   "lines": 58,
   "features": [
    "agent",
    "think",
    "pipeline",
    "lambda",
    "fail",
    "multi_cell"
   ],
   "cells": [
    "Audit",
    "Reviewer",
    "AuditTest"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/horde_rounds",
   "domain": "agents",
   "title": "A population simulation in rounds: every agent of a round sees the same",
   "summary": "A population simulation in rounds: every agent of a round sees the same world (snapshot), results are applied at the end in input order (apply), random() is seeded per task, and each agent remembers its last round (instance) — the same seed gives the same simulation, run after run. on_done starts the next round. Run: SOMA_LLM_MOCK=echo soma run horde_rounds.cell main 1000 10 Test: SOMA_LLM_MOCK=echo soma test horde_rounds.cell",
   "url": "https://soma-lang.dev/corpus/agents/horde_rounds.cell",
   "repo_path": "examples/corpus/agents/horde_rounds.cell",
   "lines": 62,
   "features": [
    "agent",
    "think",
    "pipeline",
    "lambda",
    "multi_cell"
   ],
   "cells": [
    "Market",
    "Shopper",
    "RoundsTest"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/memory_agent",
   "domain": "agents",
   "title": "Agent with persistent memory via remember()/recall()",
   "summary": "Agent with persistent memory via remember()/recall(). Demonstrates: the remember/recall builtins backed by a [persistent] slot, a knowledge-base lifecycle, and recall() returning () for unknown keys (null-checked with ??). Run: SOMA_LLM_MOCK=echo soma run memory_agent.cell --signal learn \"capital\" \"Paris\" Test: SOMA_LLM_MOCK=echo soma test memory_agent.cell",
   "url": "https://soma-lang.dev/corpus/agents/memory_agent.cell",
   "repo_path": "examples/corpus/agents/memory_agent.cell",
   "lines": 61,
   "features": [
    "state_machine",
    "agent",
    "think",
    "try"
   ],
   "cells": [
    "Librarian",
    "LibrarianTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/multi_agent_pipeline",
   "domain": "agents",
   "title": "Multi-agent content pipeline with verified handoffs",
   "summary": "Multi-agent content pipeline with verified handoffs. Demonstrates: delegate() across agent cells, each agent owning its own lifecycle machine, and a coordinator whose pipeline state machine proves the chain always terminates. Deterministic tool stubs keep it testable. Run: SOMA_LLM_MOCK=echo soma run multi_agent_pipeline.cell --signal produce \"soma\" Test: SOMA_LLM_MOCK=echo soma test multi_agent_pipeline.cell",
   "url": "https://soma-lang.dev/corpus/agents/multi_agent_pipeline.cell",
   "repo_path": "examples/corpus/agents/multi_agent_pipeline.cell",
   "lines": 70,
   "features": [
    "state_machine",
    "agent",
    "multi_cell"
   ],
   "cells": [
    "Outliner",
    "Drafter",
    "Editor",
    "PipelineTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/planner",
   "domain": "agents",
   "title": "Planning agent: decompose a goal into ordered subtasks, then execute",
   "summary": "Planning agent: decompose a goal into ordered subtasks, then execute. Demonstrates: a plan/execute lifecycle, building a task list with range() and push(), and reporting progress. The decomposition is deterministic so the corpus can verify the plan shape without an LLM. Run: SOMA_LLM_MOCK=echo soma run planner.cell --signal plan \"ship feature\" 3 Test: SOMA_LLM_MOCK=echo soma test planner.cell",
   "url": "https://soma-lang.dev/corpus/agents/planner.cell",
   "repo_path": "examples/corpus/agents/planner.cell",
   "lines": 64,
   "features": [
    "state_machine",
    "agent",
    "fail"
   ],
   "cells": [
    "Planner",
    "PlannerTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/react_calculator",
   "domain": "agents",
   "title": "A ReAct-style agent whose tools are real, deterministic computations",
   "summary": "A ReAct-style agent whose tools are real, deterministic computations. Demonstrates: face `tool` declarations that the LLM can call, plus the tool handlers being directly unit-tested (they are ordinary handlers). The think() call dispatches tools automatically; the tools themselves need no network, so the corpus can verify them. Run: SOMA_LLM_MOCK=echo soma run react_calculator.cell --signal solve \"2 and 3\" Test: SOMA_LLM_MOCK=echo soma test react_calculator.cell",
   "url": "https://soma-lang.dev/corpus/agents/react_calculator.cell",
   "repo_path": "examples/corpus/agents/react_calculator.cell",
   "lines": 63,
   "features": [
    "state_machine",
    "agent",
    "think",
    "pipeline",
    "try",
    "lambda",
    "tools"
   ],
   "cells": [
    "Calc",
    "CalcTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/sentiment_router",
   "domain": "agents",
   "title": "Sentiment-routing agent: classify a message, route by polarity",
   "summary": "Sentiment-routing agent: classify a message, route by polarity. Demonstrates: a match-based deterministic classifier as a tool, a router that branches the lifecycle on the result, and group_by-style bucketing over a batch. think() is available for the fuzzy path but tools are tested. Run: SOMA_LLM_MOCK=echo soma run sentiment_router.cell --signal route \"I love this\" Test: SOMA_LLM_MOCK=echo soma test sentiment_router.cell",
   "url": "https://soma-lang.dev/corpus/agents/sentiment_router.cell",
   "repo_path": "examples/corpus/agents/sentiment_router.cell",
   "lines": 67,
   "features": [
    "state_machine",
    "agent",
    "think",
    "match",
    "tools"
   ],
   "cells": [
    "Router",
    "RouterTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/tool_dispatcher",
   "domain": "agents",
   "title": "Reflective tool-dispatch agent: routes a named action to the right tool",
   "summary": "Reflective tool-dispatch agent: routes a named action to the right tool. Demonstrates: several `tool` declarations, a manual dispatcher that mirrors what think() does automatically (so the routing logic is unit-testable), and an unknown-action path that lands in failed. Run: SOMA_LLM_MOCK=echo soma run tool_dispatcher.cell --signal act \"reverse\" \"abc\" Test: SOMA_LLM_MOCK=echo soma test tool_dispatcher.cell",
   "url": "https://soma-lang.dev/corpus/agents/tool_dispatcher.cell",
   "repo_path": "examples/corpus/agents/tool_dispatcher.cell",
   "lines": 77,
   "features": [
    "state_machine",
    "agent",
    "think",
    "match",
    "try",
    "tools"
   ],
   "cells": [
    "Toolbox",
    "ToolboxTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/trace_audit",
   "domain": "agents",
   "title": "Self-auditing agent: it inspects its own execution trace",
   "summary": "Self-auditing agent: it inspects its own execution trace. Demonstrates: trace() returning the structured log of every think()/tool/ approval, clear_trace() resetting it, and using the trace length as an observable the agent reports back. No network needed. Run: SOMA_LLM_MOCK=echo soma run trace_audit.cell --signal investigate \"fraud\" Test: SOMA_LLM_MOCK=echo soma test trace_audit.cell",
   "url": "https://soma-lang.dev/corpus/agents/trace_audit.cell",
   "repo_path": "examples/corpus/agents/trace_audit.cell",
   "lines": 59,
   "features": [
    "state_machine",
    "agent",
    "think",
    "try",
    "tools"
   ],
   "cells": [
    "Auditor",
    "AuditTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/triage_agent",
   "domain": "agents",
   "title": "Support-ticket triage agent",
   "summary": "Support-ticket triage agent. Demonstrates: a verified lifecycle state machine, set_budget cap, tool handlers with deterministic keyword classification (no LLM call — see services/refund_agent.cell for think() + validated JSON output), and a test cell that runs without any network. Run: SOMA_LLM_MOCK=echo soma run triage_agent.cell --signal triage \"login broken\" Test: SOMA_LLM_MOCK=echo soma test triage_agent.cell",
   "url": "https://soma-lang.dev/corpus/agents/triage_agent.cell",
   "repo_path": "examples/corpus/agents/triage_agent.cell",
   "lines": 65,
   "features": [
    "state_machine",
    "agent",
    "think",
    "tools"
   ],
   "cells": [
    "Triage",
    "TriageTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/turn_bounded_chat",
   "domain": "agents",
   "title": "Turn-bounded conversation agent — proves a chat loop terminates",
   "summary": "Turn-bounded conversation agent — proves a chat loop terminates. Demonstrates: a fixed max-turns loop (no unbounded `chatting -> chatting` cycle that would break liveness), persistent transcript, and clear_context() between sessions. The bound is the verification-friendly idiom for \"loops\". Run: SOMA_LLM_MOCK=echo soma run turn_bounded_chat.cell --signal converse \"hi\" 2 Test: SOMA_LLM_MOCK=echo soma test turn_bounded_chat.cell",
   "url": "https://soma-lang.dev/corpus/agents/turn_bounded_chat.cell",
   "repo_path": "examples/corpus/agents/turn_bounded_chat.cell",
   "lines": 61,
   "features": [
    "state_machine",
    "agent",
    "think",
    "try",
    "fail"
   ],
   "cells": [
    "Chatbot",
    "ChatTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/typed_lifecycle",
   "domain": "agents",
   "title": "Agent lifecycle typed against a sum type — typos become compile errors",
   "summary": "Agent lifecycle typed against a sum type — typos become compile errors. Demonstrates: `cell type` variants typing a `state X: T { }` machine, transition() taking a VARIANT not a string, get_status() returning the variant name as a string, and an exhaustive match over the status. Run: SOMA_LLM_MOCK=echo soma run typed_lifecycle.cell --signal handle \"refund\" Test: SOMA_LLM_MOCK=echo soma test typed_lifecycle.cell",
   "url": "https://soma-lang.dev/corpus/agents/typed_lifecycle.cell",
   "repo_path": "examples/corpus/agents/typed_lifecycle.cell",
   "lines": 57,
   "features": [
    "state_machine",
    "agent",
    "sum_type",
    "match"
   ],
   "cells": [
    "TaskStatus",
    "Worker",
    "WorkerTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  },
  {
   "id": "agents/verified_termination",
   "domain": "agents",
   "title": "The killer feature: an agent whose termination is PROVEN by soma verify",
   "summary": "The killer feature: an agent whose termination is PROVEN by soma verify. The lifecycle has a single terminal set {done, failed} reachable from every state, a `* -> failed` catch-all, and the matching soma.toml below drives `soma verify` to prove deadlock-freedom and liveness (eventually done|failed). Check: soma check verified_termination.cell Verify: soma verify verified_termination.cell (uses the soma.toml beside it) Run: SOMA_LLM_MOCK=echo soma run verified_termination.cell --signal solve \"x\" Test: SOMA_LLM_MOCK=echo soma test verified_termination.cell",
   "url": "https://soma-lang.dev/corpus/agents/verified_termination.cell",
   "repo_path": "examples/corpus/agents/verified_termination.cell",
   "lines": 52,
   "features": [
    "state_machine",
    "agent",
    "think",
    "try"
   ],
   "cells": [
    "Solver",
    "SolverTests"
   ],
   "manifest": "https://soma-lang.dev/corpus/agents/soma.toml"
  }
 ]
}