# Firebreak v0.1.0 - Table of Contents

> Static analysis for OTP supervision trees and the coupling that crosses them. Flags structural anti-patterns and the cross-subtree dependencies the supervision tree alone can't show - no app boot, no LLM, CI-friendly.

## Pages

- [Firebreak](readme.md)
- [Changelog](changelog.md)
- [The Firebreak model IR — a contract for backends](model-ir-contract.md)

## Modules

- [Firebreak](Firebreak.md): Firebreak reads the supervision structure of an Elixir/OTP application and
reports where the *declared* failure topology (the supervision tree) diverges
from the *actual* one (the runtime coupling between processes).
- [Firebreak.Analysis](Firebreak.Analysis.md): The aggregate result of analysing a project: the parsed modules, the
resolved coupling edges, the supervision forest (subtree membership), and
the findings produced by the checks.

- [Firebreak.Baseline](Firebreak.Baseline.md): CI plumbing: a committed allowlist (`.firebreak.exs`) and a finding baseline so
a pipeline can fail only on *new* coupling, not on the backlog it inherited.
- [Firebreak.BlastRadius](Firebreak.BlastRadius.md): Tier-2 analysis — the part no existing tool does.
- [Firebreak.BootOrder](Firebreak.BootOrder.md): Boot order ≠ dependency order.
- [Firebreak.Checks](Firebreak.Checks.md): Tier-1 structural checks: facts you can read straight off the supervision
tree and each process module, no cross-module graph needed. Cheap, fast,
deterministic — the kind of thing that belongs in a CI gate.

- [Firebreak.Child](Firebreak.Child.md): A single child entry inside a supervisor's child list.
- [Firebreak.Conformance](Firebreak.Conformance.md): Supervision-topology conformance: diff the *intended* tree against the one the
code actually produces, and report the drift.
- [Firebreak.Coupling](Firebreak.Coupling.md): Resolves the per-module coupling edges produced by `Firebreak.Source` into a
global graph.
- [Firebreak.Cycles](Firebreak.Cycles.md): Detects cycles of *synchronous* calls in the coupling graph — a deadlock hazard
the supervision tree can't show.
- [Firebreak.Edge](Firebreak.Edge.md): A coupling edge: a runtime dependency from one module to another that is
*not* expressed by the supervision tree.
- [Firebreak.FailureSim](Firebreak.FailureSim.md): Per-process failure simulation — "if this process crashes right now, what
actually goes down, and who blocks?"
- [Firebreak.FailureViz](Firebreak.FailureViz.md): Renders the *failure modes* in the model IR as a Mermaid diagram — making the
gap firebreak hunts for visible: which external caller blocks on `:noproc` when
a process in another supervision subtree restarts.
- [Firebreak.Finding](Firebreak.Finding.md): A single issue surfaced by an analysis pass. Findings carry a stable
`check` id (so they can be allowlisted in CI), a severity, and the source
location they point at.

- [Firebreak.Forest](Firebreak.Forest.md): Builds the supervision forest from parsed modules: who supervises whom, which
supervisors are roots, and the full set of descendant modules in each
supervisor's subtree.
- [Firebreak.JSON](Firebreak.JSON.md): A tiny, zero-dependency JSON encoder — just enough to emit Firebreak's report as
a CI artifact without pulling in a dependency. A CI gate should be boring and
offline; that includes its own dependency footprint.

- [Firebreak.Lockstep](Firebreak.Lockstep.md): Generates [lockstep](https://hex.pm/packages/lockstep) concurrency-test
*scaffolds* from firebreak's model IR — the dynamic counterpart to the TLA+
backend.
- [Firebreak.Model](Firebreak.Model.md): A spec-generation IR: per supervisor, exactly the facts a *lifecycle* model
needs — and nothing it doesn't.
- [Firebreak.ModuleInfo](Firebreak.ModuleInfo.md): Everything we learned about a single module: what kind of OTP citizen it is,
its supervision configuration (if a supervisor), the names it registers
itself under, and its outgoing coupling edges.
- [Firebreak.Observe](Firebreak.Observe.md): Ground-truth enrichment from a *live* BEAM node.
- [Firebreak.Orphans](Firebreak.Orphans.md): Finds stateful processes that no supervisor starts.
- [Firebreak.Quint](Firebreak.Quint.md): Generates a [Quint](https://quint-lang.org) lifecycle module from a
`Firebreak.Model` bundle — the same supervision-lifecycle model as
`Firebreak.Tla`, in Quint's syntax.
- [Firebreak.Report](Firebreak.Report.md): Renders an `Firebreak.Analysis` as human-readable text or as JSON (the CI
artifact / handoff format).

- [Firebreak.RiskScore](Firebreak.RiskScore.md): A single, transparent supervision-risk number per project (and per supervisor),
derived from the model IR — for dashboards and for tracking whether a tree is
getting riskier over time.
- [Firebreak.Runtime](Firebreak.Runtime.md): Exact supervision-tree extraction by the canonical OTP method.
- [Firebreak.RuntimeOverlay](Firebreak.RuntimeOverlay.md): Join the static model IR against a live node's observed reality.
- [Firebreak.Snapshot](Firebreak.Snapshot.md): A point-in-time reading of a live node's runtime shape, produced by
`Firebreak.Observe.snapshot/2`. Pure data — every field describes what was
actually running, so anything derived from it carries `:exact` confidence.
- [Firebreak.Source](Firebreak.Source.md): Parses Elixir source into `Firebreak.ModuleInfo` structs.
- [Firebreak.Tla](Firebreak.Tla.md): Generates a TLA+ lifecycle module + TLC config from a `Firebreak.Model` bundle.
- [Firebreak.Viz](Firebreak.Viz.md): Renders an `Firebreak.Analysis` as a graph in DOT (Graphviz) or Mermaid.
- [Firebreak.WhatIf](Firebreak.WhatIf.md): Topology refactor simulation: mutate the supervision structure, re-run the
*real* analysis on the hypothetical, and diff the synchronous cross-tree
crossings — so you can answer "does this move actually fix the coupling, or just
relocate it?" before touching code.

## Mix Tasks

- [mix firebreak](Mix.Tasks.Firebreak.md): Analyses an Elixir/OTP project's supervision structure and the runtime coupling
between processes, reporting where the supervision tree understates the real
failure topology.
- [mix firebreak.lockstep](Mix.Tasks.Firebreak.Lockstep.md): Generates a [lockstep](https://hex.pm/packages/lockstep) `ctest` scaffold per
synchronous cross-tree crossing firebreak found — the dynamic counterpart to
`mix firebreak.spec` (which generates TLA+). Where the TLA+ spec *proves* the
cross-tree `:noproc` failure is reachable in a model, the lockstep scaffold is
the starting point for a test that reproduces it in the running BEAM.
- [mix firebreak.spec](Mix.Tasks.Firebreak.Spec.md): Generates a formal lifecycle spec per supervisor, derived purely from
firebreak's supervision model (`mix firebreak --format model`). Each spec models
the restart/escalation lifecycle and — only where firebreak found a synchronous
cross-tree crossing — an external-caller availability property.

