Crate differential_schema 

The frozen JSON contract for differential reading plans.

This crate is the product boundary: every consumer (shadow-branch stack, TUI, forge review) depends on these types and nothing else. Consumer conveniences must not leak in here.

Contract rules:

• schema_version is 1. 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.

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.

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

Enums

Disposition

Effort

GeneratedBy

ReadAction

Role

SchemaError

SourceKind

Constants

SCHEMA_VERSION