Expand description
The explain layer: a local, optional model that narrates a fork amberfork-align already
computed (issue #10, Phase 2 / Zone 3 of the design doc).
The deterministic aligner stays the headline. This crate never localizes — it reads a
finished amberfork_model::DiffResult plus a narrow content window and only ever
describes or speculates. Two guardrails are enforced in the types rather than left to
convention:
ExplainContexthands aJudgethe fork step (+kneighbours) it is scoped to reason about, never the two full trajectories — a judge cannot hunt for a different fork because it never sees content outside the window.groundvalidates a judge’s claimed fork index against theDiffResultit was asked about before the result is trusted; an explanation that contradicts the aligner is rejected, never rendered.
Alongside the trait: ScriptedJudge (the in-process test double that keeps cargo test --workspace offline) and OllamaJudge (the live provider — a local Ollama server, no
cloud call, no API key). tokio is deliberately absent from this crate’s own dependencies:
Judge::explain is a plain async fn, and the runtime that drives it belongs to the caller
(the CLI), the same I/O-edge quarantine amberfork-replay uses.
Structs§
- Explain
Context - What a
crate::Judgeis handed: the fullDiffResult(so it can see the fork, attribution, and warnings) plus a narrow content window — the fork step and itskneighbours on each side, never the two full trajectories. This is guardrail #3 from the issue: a judge cannot hunt for a different fork because it never sees content outside the window. - Explanation
- A judge’s raw claim about a diff — not yet trusted.
crate::groundvalidates it against theamberfork_model::DiffResultit was asked about before a caller may render it. - Grounded
- An
Explanationthat has been checked against theDiffResultit claims to describe — safe for a caller to render. The only way to get one isground. - Grounding
Error - A judge’s claim did not match the
DiffResultit was asked about. - Ollama
Judge - The production
Judge. Never asks the model to report where the fork is —Explanation::fork_indexis set from theExplainContextitself, not parsed from model output, so the model structurally cannot mis-localize (design guardrail #1); it only ever narrates the window it’s handed. - Scripted
Judge - An in-process
Judgethat serves a fixed script of results in order. - Step
Snapshot - A minimal, judge-safe view of one step: enough content to narrate, deliberately shaped like
amberfork_model::Stepbut never the step itself — a judge reads a copy, not a borrow of the trace, so widening what it can reach later is a conscious type change here, not a visibility slip.
Enums§
- Judge
Error - Why a judge could not produce an explanation.
- Side
- Which run a windowed
StepSnapshotcame from — the same neutrala/bconventionDiffResultuses.
Traits§
- Judge
- One operation: narrate the fork an
ExplainContextalready points at. The aligner has already decided where; a judge only ever describes and suggests (design guardrail #1) — nothing in this trait lets an implementation report a different fork, andcrate::groundis the enforcement point that catches an implementation that tries anyway.
Functions§
- ground
- Validate a judge’s claim against the result it was asked about.