Consensus Layer Knowledge Base

# Consensus Layer KB — Layout

## Purpose

Canonical structure for the consensus-layer knowledge base in the repo. Tools (Tutor, Workbench, Test Scaffold, Diagnostician, Change Reviewer) read from this structure; humans navigate it directly. Stable cross-references depend on the conventions below.

## Top-level location

`platform-sdk/docs/consensus-layer/`, parallel to the existing `platform-sdk/docs/proposals/consensus-layer/`. Movable later if a better home emerges.

## Directory tree

```
platform-sdk/docs/consensus-layer/
├── README.md entry point: what's here, how to navigate, which sections each tool consumes
│
├── concepts/ foundational concepts, canonical definitions
│ ├── README.md
│ ├── hashgraph-dag.md
│ ├── rounds-and-witnesses.md
│ ├── strongly-seeing.md
│ ├── birth-round.md
│ └── ...
│
├── glossary.md single file, ~50 terms
│
├── architecture/
│ ├── README.md
│ ├── overview.md high-level shape; adapts from Consensus-Layer.md
│ ├── topics/ one file per topic (the 11)
│ │ ├── wiring-framework.md
│ │ ├── gossip.md
│ │ ├── event-intake.md
│ │ ├── event-creator.md
│ │ ├── hashgraph.md
│ │ ├── health-monitor-and-backpressure.md
│ │ ├── reasons-not-to-gossip.md
│ │ ├── signed-state-management.md
│ │ ├── restart-and-pces.md
│ │ ├── freeze-and-upgrade.md
│ │ └── reconnect.md
│ └── interfaces/
│ └── consensus-execution-boundary.md
│
├── invariants.md single file (catalog of INV-NNN entries)
│
├── decisions/ ADR-style records, per file
│ ├── README.md
│ └── ADR-NNN-short-slug.md
│
├── tunables.md single file (catalog of parameters)
│
├── delta-map/ one file per topic, flat
│ ├── README.md
│ ├── wiring-framework.md
│ ├── gossip.md
│ ├── event-intake.md
│ ├── event-creator.md
│ ├── hashgraph.md
│ ├── health-monitor-and-backpressure.md
│ ├── reasons-not-to-gossip.md
│ ├── signed-state-management.md
│ ├── restart-and-pces.md
│ ├── freeze-and-upgrade.md
│ └── reconnect.md
│
├── scenarios/ per file, with sequential IDs
│ ├── README.md
│ └── SCN-NNN-short-slug.md
│
├── questions/ working Q&A artifacts from the sprint
│ ├── README.md
│ ├── Q1-foundational-rationale.md
│ ├── Q2-...md
│ └── ...
│
└── tutor/ curriculum content; internal structure deferred
```

`tools/` is intentionally absent — see deferred decisions below.

## File naming and IDs

- Catalog entries use sequential IDs with descriptive slugs:
- ADRs: `decisions/ADR-NNN-short-slug.md`
- Scenarios: `scenarios/SCN-NNN-short-slug.md`
- IDs are zero-padded to three digits.
- Titles live in YAML frontmatter or as the H1 inside the file.
- Cross-references from other files use the ID only (e.g., "See ADR-007").
- Architecture topic files and delta-map files are named directly after the topic (no ID prefix), e.g., `architecture/topics/hashgraph.md`, `delta-map/hashgraph.md`.

## Section conventions

### `README.md` (top-level)
Entry point. What's in this directory; how to navigate; which sections each tool consumes.

### `concepts/`
Foundational definitions and canonical mental models. One file per concept (hashgraph DAG, rounds and witnesses, strongly-seeing, birth-round, etc.). Used by the Tutor curriculum to ground later content.

### `glossary.md`
Single file. ~50 terms. The canonical definition for each term referenced anywhere else in the KB. Disambiguates overloaded vocabulary (round / consensus round / birth round; ancient / expired / stale).

### `architecture/`
The topic-organized lens on the consensus layer.
- `architecture/overview.md` — adapts the high-level shape from `Consensus-Layer.md` for KB use.
- `architecture/topics/` — one file per topic (the 11). Each describes the topic's responsibilities, state, contracts, and links to related concepts, invariants, decisions, and scenarios.
- `architecture/interfaces/consensus-execution-boundary.md` — the Consensus public API (`initialize`, `destroy`, `nextRound`, `onBehind`, `onPreHandleEvent`, `getTransactionsForEvent`, etc.).

### `invariants.md`
Single file. Catalog of "must always be true" claims. Each entry has an ID (INV-NNN), description, severity, and the topics/components it touches. Load-bearing for the Change Reviewer and Diagnostician tools.

### `decisions/`
Per-file ADRs. Each ADR records context, decision, alternatives considered, and consequences. Standard ADR pattern. The README is the chronological index.

### `tunables.md`
Single file. Catalog of configurable parameters with effects, ranges, and fragility (`N`, `Z`, `max_event_creation_frequency`, health-monitor thresholds, etc.).

### `delta-map/`
Per-topic status of "current code vs. proposed design": done / partial / not started / divergent. Eleven flat files, one per topic. Updated as work progresses.

### `scenarios/`
Per-file scenario entries. Each captures an edge case, near-miss, or historical incident with timeline, evidence, and (where known) mitigation. Catalog grows over time via Diagnostician/Workbench handoffs (manually curated, not auto-fed).

### `questions/`
Question lists posed during the sprint, with answers preserved. Each Q-list is a working artifact whose answers feed KB content. Numbered Q1, Q2, etc. Captured in the repo because the answers themselves are knowledge.

### `tutor/`
Curriculum content for the Tutor tool. Internal organization deferred — left to the Tutor implementation.

## Deferred decisions

### `tools/`
Location of tool configurations and briefs (Tutor, Workbench, Test Scaffold, Diagnostician, Change Reviewer) is deferred. The team's convention typically splits code from docs; the right home for each tool's `CLAUDE.md` and brief will be decided when the tools are specified in detail.

### Tutor internal structure
Internal organization of `tutor/` is left to the Tutor implementation — authoring will reveal what shape works.

## Index README convention

Every populated directory has a `README.md` that serves as the canonical index — a table mapping IDs (where applicable) to titles, with brief descriptions. Tools cross-reference by ID; humans navigate by title in listings.