# samudralaajaykumarrr/failuremesh architecture

> Architecture diagram of the GitHub repository samudralaajaykumarrr/failuremesh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samudralaajaykumarrr/failuremesh
- Repository: https://github.com/samudralaajaykumarrr/failuremesh

## Overview

FailureMesh turns known failure mechanisms into bounded experiments and machine-checked evidence. The primary workflow is an engineer invoking the CLI to match a Portable Failure Contract (PFC) against an Architecture Contract (AC), compile and safety-plan an experiment, execute it, and receive a verifier verdict with evidence. Separate CLI branches model duplicate delivery, stale-worker fencing, and two historical incidents. The local corpus register supports manual metadata intake and immutable manifests. The graph follows documented capabilities; wiring for unsampled subsystems is shown only where the README or sampled code supports it.

Main entry points: [`cmd/failuremesh/main.go`](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/cmd/failuremesh/main.go) (FailureMesh CLI), [`cmd/failuremesh/corpus.go`](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/cmd/failuremesh/corpus.go) (Corpus command), [`internal/phase1/run.go`](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/phase1/run.go) (Phase 1 flow), [`internal/pfc2/run.go`](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/pfc2/run.go) (Duplicate delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI workflow"]
  node_cli["FailureMesh CLI<br/>[main.go]"]
  node_phase1contracts["PFC and AC<br/>[contracts.go]"]
  node_contracts["Versioned PFC contracts"]
end

subgraph group_experiments["Failure experiments"]
  node_phase1flow["Phase 1 flow<br/>[run.go]"]
  node_pfc2flow["Duplicate delivery<br/>[run.go]"]
  node_pfc3flow["Stale-worker fencing<br/>[run.go]"]
  node_iceberg["Iceberg reproduction<br/>[model.go]"]
  node_githubcascade["GitHub cascade<br/>[model.go]"]
  node_verdict["Verifier verdict<br/>[run.go]"]
end

subgraph group_evidence["Evidence and corpus"]
  node_corpuscli["Corpus command<br/>[corpus.go]"]
  node_corpusmodel["Corpus records<br/>[model.go]"]
  node_corpussemantics["Corpus validation<br/>[semantics.go]"]
  node_corpusstore[("Corpus store<br/>[store.go]")]
  node_evidenceassessment["Evidence assessment<br/>[assess.go]"]
  node_evidencevalidation["Evidence validation<br/>[validate.go]"]
end

subgraph group_state["Runtime state"]
  node_postgres[("PostgreSQL")]
end

node_engineer(("Engineer"))

node_engineer -->|"invokes"| node_cli
node_cli -->|"loads and matches"| node_phase1contracts
node_cli -->|"compiles, plans, runs"| node_phase1flow
node_phase1flow -->|"verifies evidence"| node_verdict
node_phase1flow -->|"reads and writes"| node_postgres
node_cli -->|"runs PFC 2"| node_pfc2flow
node_pfc2flow -->|"reads and writes"| node_postgres
node_cli -->|"runs PFC 3"| node_pfc3flow
node_pfc3flow -->|"reads and writes"| node_postgres
node_cli -->|"runs reproduction"| node_iceberg
node_iceberg -->|"reads and writes"| node_postgres
node_cli -->|"runs reproduction"| node_githubcascade
node_githubcascade -->|"reads and writes"| node_postgres
node_cli -->|"dispatches corpus"| node_corpuscli
node_corpuscli -->|"processes records"| node_corpusmodel
node_corpuscli -->|"validates corpus"| node_corpussemantics
node_corpuscli -->|"publishes and reads"| node_corpusstore
node_corpussemantics -->|"checks semantics"| node_corpusmodel
node_evidenceassessment -->|"validates inputs"| node_evidencevalidation
node_contracts -.->|"defines contract"| node_phase1contracts

click node_cli "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/cmd/failuremesh/main.go"
click node_phase1contracts "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/phase1/contracts.go"
click node_phase1flow "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/phase1/run.go"
click node_pfc2flow "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/pfc2/run.go"
click node_pfc3flow "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/pfc3/run.go"
click node_iceberg "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/historical/iceberg16282/model.go"
click node_githubcascade "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/historical/githubmay4/model.go"
click node_verdict "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/phase1/run.go"
click node_corpuscli "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/cmd/failuremesh/corpus.go"
click node_corpusmodel "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/corpus/model.go"
click node_corpussemantics "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/corpus/semantics.go"
click node_corpusstore "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/corpus/store.go"
click node_evidenceassessment "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/evidence/assess.go"
click node_evidencevalidation "https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/evidence/validate.go"
click node_contracts "https://github.com/samudralaajaykumarrr/failuremesh/tree/main/contracts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_phase1contracts,node_contracts toneBlue
class node_phase1flow,node_pfc2flow,node_pfc3flow,node_iceberg,node_githubcascade,node_verdict toneAmber
class node_corpuscli,node_corpusmodel,node_corpussemantics,node_corpusstore,node_evidenceassessment,node_evidencevalidation toneMint
class node_postgres toneRose
class node_engineer toneIndigo
```

## Components

### CLI workflow

- [FailureMesh CLI](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/cmd/failuremesh/main.go): `cmd/failuremesh/main.go`
- [PFC and AC](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/phase1/contracts.go): `internal/phase1/contracts.go`
- [Versioned PFC contracts](https://github.com/samudralaajaykumarrr/failuremesh/tree/main/contracts): `contracts`

### Failure experiments

- [Phase 1 flow](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/phase1/run.go): `internal/phase1/run.go`
- [Duplicate delivery](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/pfc2/run.go): `internal/pfc2/run.go`
- [Stale-worker fencing](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/pfc3/run.go): `internal/pfc3/run.go`
- [Iceberg reproduction](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/historical/iceberg16282/model.go): `internal/historical/iceberg16282/model.go`
- [GitHub cascade](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/historical/githubmay4/model.go): `internal/historical/githubmay4/model.go`
- [Verifier verdict](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/phase1/run.go): `internal/phase1/run.go`

### Evidence and corpus

- [Corpus command](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/cmd/failuremesh/corpus.go): `cmd/failuremesh/corpus.go`
- [Corpus records](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/corpus/model.go): `internal/corpus/model.go`
- [Corpus validation](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/corpus/semantics.go): `internal/corpus/semantics.go`
- [Corpus store](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/corpus/store.go): `internal/corpus/store.go`
- [Evidence assessment](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/evidence/assess.go): `internal/evidence/assess.go`
- [Evidence validation](https://github.com/samudralaajaykumarrr/failuremesh/blob/main/internal/evidence/validate.go): `internal/evidence/validate.go`

### Runtime state

- **PostgreSQL**

### Other components

- **Engineer**

## Connections

- Engineer → FailureMesh CLI: invokes
- FailureMesh CLI → PFC and AC: loads and matches
- FailureMesh CLI → Phase 1 flow: compiles, plans, runs
- Phase 1 flow → Verifier verdict: verifies evidence
- Phase 1 flow → PostgreSQL: reads and writes
- FailureMesh CLI → Duplicate delivery: runs PFC 2
- Duplicate delivery → PostgreSQL: reads and writes
- FailureMesh CLI → Stale-worker fencing: runs PFC 3
- Stale-worker fencing → PostgreSQL: reads and writes
- FailureMesh CLI → Iceberg reproduction: runs reproduction
- Iceberg reproduction → PostgreSQL: reads and writes
- FailureMesh CLI → GitHub cascade: runs reproduction
- GitHub cascade → PostgreSQL: reads and writes
- FailureMesh CLI → Corpus command: dispatches corpus
- Corpus command → Corpus records: processes records
- Corpus command → Corpus validation: validates corpus
- Corpus command → Corpus store: publishes and reads
- Corpus validation → Corpus records: checks semantics
- Evidence assessment → Evidence validation: validates inputs
- Versioned PFC contracts → PFC and AC: defines contract