Skip to main content

Crate amberfork_judge

Crate amberfork_judge 

Source
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:

  • ExplainContext hands a Judge the fork step (+ k neighbours) 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.
  • ground validates a judge’s claimed fork index against the DiffResult it 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§

ExplainContext
What a crate::Judge is handed: the full DiffResult (so it can see the fork, attribution, and warnings) plus a narrow content window — the fork step and its k neighbours 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::ground validates it against the amberfork_model::DiffResult it was asked about before a caller may render it.
Grounded
An Explanation that has been checked against the DiffResult it claims to describe — safe for a caller to render. The only way to get one is ground.
GroundingError
A judge’s claim did not match the DiffResult it was asked about.
OllamaJudge
The production Judge. Never asks the model to report where the fork is — Explanation::fork_index is set from the ExplainContext itself, not parsed from model output, so the model structurally cannot mis-localize (design guardrail #1); it only ever narrates the window it’s handed.
ScriptedJudge
An in-process Judge that serves a fixed script of results in order.
StepSnapshot
A minimal, judge-safe view of one step: enough content to narrate, deliberately shaped like amberfork_model::Step but 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§

JudgeError
Why a judge could not produce an explanation.
Side
Which run a windowed StepSnapshot came from — the same neutral a/b convention DiffResult uses.

Traits§

Judge
One operation: narrate the fork an ExplainContext already 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, and crate::ground is the enforcement point that catches an implementation that tries anyway.

Functions§

ground
Validate a judge’s claim against the result it was asked about.