The Filecoin Kernel Monitor

Machine-verifiable health monitoring for the Filecoin kernel functions, from public sources.

Live dashboard →

---

The Filecoin ProPGF program funds teams that maintain the network's core functions. This repo tracks the health of those functions from public sources.

The Filecoin kernel is the set of functions the network cannot operate without, split into irreplaceable and essential tiers and catalogued in registry/_kernel.yaml. Each funded team declares, in a public manifest, which kernel functions it maintains and how to check each one: a metric, a public source for it, and an SLA (the threshold it commits to — a team may also have none yet, which just means "monitored, not scored"). The pipeline fetches each source, evaluates against the threshold as it stood that day, and publishes the result. Every value comes from the source, not from self-reporting.

Two append-only tables carry the history: data/observations.csv records what was measured, data/thresholds.csv records what was promised on that same day. Neither stores an outcome — the dashboard joins them at render time and derives pass/fail/unscored/indeterminate, so fixing a threshold fixes the judgment on every past reading instead of leaving it scored against a bar nobody agreed to.

FUNCTION → SLA → SOURCE → READING → EVALUATION → RECOMMENDATION → VERDICT
        (the repo: what was promised)   (the pipeline: what was measured)   (a human: the call)

The live dashboard shows each kernel function's current status — green (OK), red (a recent interruption), or amber (indeterminate) — alongside the ProPGF funding for each team.

Start here

You are…	Go to
A funded team writing or editing your manifest	docs/guide-projects.md
A ProPGF reviewer or committee member	docs/guide-reviewers.md
Using a coding agent (Claude Code, Cursor, …)	CLAUDE.md — both guides are agent-ready too
An agent answering questions without cloning	SKILL.md — point yours at the raw URL

How a team commits to a metric

A commitment is data, not a promise in prose. Each entry in a team's manifest (registry/<team>.yaml) is a metric, a public source, and a threshold:

- function_id: mainnet-block-explorer
  origin: external-pr           # who proposed it: oso | karma | external-pr
  tier: essential
  category: 'UX/DX'
  sub_category: 'Explorers and Tooling'
  sla:
    statement: "Explorer keeps pace with the chain: largest gap between indexed tipsets <= 90s"
    metric: explorer_max_tipset_gap_seconds
    threshold: { op: "<=", value: 90 }
    cadence: daily
  source:
    adapter: oso
    kind: http-json
    base_url: "https://filfox.info"
    query: "/api/v1/tipset/recent"
  transform:
    sql: "SELECT MAX(g) FROM (SELECT timestamp - LAG(timestamp) OVER (ORDER BY height) AS g FROM raw) s"

The project guide walks through choosing metrics and sources, validating offline, and opening the PR.

Contribute

Changes to registry/ ride pull requests, so the whole history of what each team promised is public and auditable. To add or change a metric:

1. Edit your team's manifest, or start a new one under registry/drafts/<team>.yaml.
2. Validate it offline: uv run python -m scripts.validate_pr registry/<team>.yaml.
3. Open a PR. CI runs the static gate; the committee can trigger a live dry-run before merge.

New source hosts need a line in registry/_allowlist.txt in the same PR — approving the PR approves the egress.

Run it locally

uv sync
uv run pytest -q                       # full deterministic suite: no network, no model
uv run fpm review chainsafe --manifest tests/fixtures/chainsafe.yaml --dev-auto-approve
uv run python -m scripts.validate_pr registry/chainsafe.yaml

Two offline, credential-free demos of the whole loop:

scripts/demo_project_flow.sh     # a team's loop: draft → validate → dry promotion → gate check
scripts/demo_reviewer_flow.sh    # committee loop: review → adjudicate → verdicts

Live modes (real fetches, real dashboard data) need an OSO_API_KEY — see the reviewer guide.

Repo map

registry/            the trust anchor (PR-governed, CI-gated)
  _kernel.yaml         the kernel taxonomy (tier / category / sub_category)
  _schema.json         manifest schema      _allowlist.txt   approved source hosts
  <team>.yaml          adopted team manifests, running live
  drafts/<team>.yaml   staging for new proposals, created on demand
src/fpm/             the pipeline: manifest → fetch → evaluate → recommend → adjudicate → land
data/                observations.csv + thresholds.csv, the append-only time series
                       (never hand-edited — written only through fpm.observations / fpm.thresholds)
scripts/             validate_pr (the PR gate), validate_draft / promote_draft, offline demos
dashboards/          propgf-kernel-health.py (marimo; uv sync --extra dashboards)
docs/                guides (project · reviewer · governance · coverage)
.github/workflows/   static gate on every PR + label-gated live dry-run + tests

Governance

registry/ changes ride PRs. A static gate runs on every PR with no secrets: it checks the schema, kernel-taxonomy conformance, the source-host allowlist, and transform-SQL safety, and prints a goalpost report — a team can't quietly loosen an SLA, because every threshold change is classified and surfaced for review, including a threshold appearing or disappearing. The committee's dry-run-ok label triggers a live dry-run that provisions the source for real and posts the observed value before merge. CODEOWNERS keeps each team's file under its own maintainers, and the kernel taxonomy itself evolves by reviewed PR.

What a funded team owes, and how an SLA is structured, is spelled out in the project guide.

A note on contracts/

registry/ is the whole of what gets measured, and it is complete in this repository: a clone can run the tests, validate a manifest and read every commitment.

contracts/<team>.facts.yaml is different. Those files carry grant contract terms -- recipient, committed amount, the §4 dependency evidence -- so they are gitignored and maintainer-local, and they are not needed to run or review anything the pipeline does. registry/_grants.yaml points at them so a maintainer can find them; on a clean clone those pointers simply do not resolve, which is expected. fpm contract is therefore a maintainer-only command and says so when the file is absent. contracts/example.facts.yaml documents the shape.

Where an entry carries no threshold, sla.unscored_reason says why in one word; the reasoning behind it lives in the facts file rather than in this public repository, because it quotes signed agreements.