Module schema 

The frozen JSON contract for differential reading plans.

This module is the product boundary (ADR 0008, superseded-in-form by ADR 0018): every consumer (shadow-branch stack, TUI, forge review) depends on these types and nothing else. It stays serde-only — consumer conveniences and engine internals must not leak in here; that discipline is enforced in review now that the crate boundary is gone.

Contract rules:

• schema_version is 3 (v3 gave every dependency edge its cause and moved the graph onto classes, ADR 0022). Readers must reject versions they do not know.
• Deserialisation tolerates unknown fields, so additive changes are non-breaking.
• groups/reading_plan are null when the grouping stage has not run. That is distinct from [], which would mean “grouping ran and produced nothing” and is always a bug. generator.stages states exactly which stages produced the document.
• Optional fields serialise as explicit null, never omitted.

Structs

Audit

Structural audit. The first four fields exist for every document; the rest are null until the grouping stage runs.

ClassEdge

One class-level dependency edge.

ClassEntry

A shape class: hunks whose diff text is identical after normalising away identifiers and literals on BOTH sides. Ids C0..Cn, numbered by descending member count. 100% hunk coverage is by construction.

Edge

One group-level dependency edge.

FileEntry

One changed file in the canonical (--no-renames) view. A rename therefore appears as a D entry plus an A entry; the rename-detected view annotates both.

ForgePosition

Generator

Group

A merged, labelled group of shape classes. Produced by the grouping stage.

HunkEntry

One canonical hunk from git diff -U0 --no-renames. Ids are positional (h0..hN in enumeration order) and do NOT survive regeneration; digest does.

PlanDocument

The one JSON document: a grouped, ordered reading plan for a diff.

ReadingStep

Remote

Source

Stats

SubmoduleChange

SymbolDef

One declaration something in the change reads.

SymbolIndex

Where each resolvable name is declared, and every token that reads one.

SymbolUse

One token that reads a SymbolDef.

Enums

Cycle

Why a dependency edge could not be honoured.

Disposition

Effort

GeneratedBy

ReadAction

Role

SchemaError

SourceKind

Constants

SCHEMA_VERSION