🥮 mooncakes.io

frontierlab

A MoonBit algorithm trace protocol and polished offline HTML visualization kit.

algorithm
trace
visualization
education
html
debugger
moon add shop1111/frontierlab@0.9.1
Download zip
Author
Version
0.9.1
License
MIT
Repository
Last updated
7 days ago
Downloads
30

Dependencies

README

#FrontierLab

FrontierLab 是一个 MoonBit 算法轨迹库。它把算法执行过程记录为带稳定实体 ID 的语义事件和场景快照，并提供检查、对比、调试、JSON 编解码和精修后的离线 HTML 可视化能力。

CI Mooncakes

在线打开 AI Trace Clinic · Mooncakes · Trace Schema v1

#安装

在 MoonBit 项目中添加依赖：

moon add shop1111/frontierlab

然后在需要使用 FrontierLab 的包中导入 shop1111/frontierlab。

#最小示例

下面的例子生成一条插入排序轨迹，再检查最终序列是否有序：

let trace = @frontierlab.insertion_sort_trace([3, 1, 2])
let result = @frontierlab.diagnose_trace(
  trace,
  contract=@frontierlab.sorted_int_sequence_contract(object_id="values"),
  expected=trace,
)
assert_true(result.passed())

这里的“轨迹规则”（代码类型为 TraceContract）是一个检查器：它检查轨迹中的 步骤或最终结果是否违反预先定义的要求，并返回具体的失败步骤和原因。 sorted_int_sequence_contract 检查最终整数序列是否有序； sequence_transition_contract 检查事件描述的变化是否与场景快照一致。

自定义算法通常按以下顺序接入：

  1. 用稳定 ID 表示元素、节点或网格单元；元素移动后 ID 不变。
  2. 用 TraceBuilder 记录 Compare、Swap、Visit、Union、Relax 等有意义的事件和对应场景。
  3. 调用 finish 得到 AlgorithmTrace。
  4. 将轨迹交给规则检查、差异分析、JSON 编解码或渲染 API。

可直接运行的完整代码见 API 示例 和集成说明。

#内置算法 Adapter

Adapter 把算法输入和执行步骤转换成统一的 AlgorithmTrace，因此这些轨迹可以 直接交给 JSON、HTML、分析、断点、diff 和诊断 API：

类别Adapter场景主要语义事件
排序insertion_sort_trace、insertion_sort_items_traceSequenceCompare、Swap
集合union_find_traceSetsCompare、Union、Update
一维 DPfibonacci_dp_trace、coin_change_dp_traceSequenceUpdate、依赖高亮
二维 DPzero_one_knapsack_dp_trace、lcs_dp_traceGridUpdate、Visit
平衡树red_black_tree_traceGraph插入、重着色、旋转、查找
路径搜索桥接search_trace_to_algorithm_traceGridVisit、Relax

Fibonacci 和零钱兑换保留各自简单的算法级入口，但内部共享一维 DP 场景表达。 红黑树支持 Insert 和 Find 操作；节点标签中的 [R]、[B] 在不修改 Trace Schema v1 的前提下持久表示颜色。

let lcs = @frontierlab.lcs_dp_trace("ABCBDAB", "BDCABA")
let tree = @frontierlab.red_black_tree_trace([
  @frontierlab.Insert(30),
  @frontierlab.Insert(10),
  @frontierlab.Insert(20),
  @frontierlab.Find(20),
])

#CLI

从源码运行统一诊断命令：

moon run cmd/main -- diagnose \
  fixtures/agent-traces/selection-sort-expected.json \
  fixtures/agent-traces/selection-sort-actual.json \
  --contract sorted-int-sequence \
  --object values \
  --format text \
  --counterexample _build/counterexample.json \
  --report _build/diagnosis.html

这组示例输入故意包含错误，所以命令返回退出码 2，并报告第一次差异在 step 10。CLI 的退出码含义为：

  • 0：输入有效，并且轨迹通过检查且与参考轨迹一致；
  • 2：输入有效，但轨迹违反规则或与参考轨迹不同；
  • 1：参数、文件、JSON 或 Schema 无效。

GitHub Release 同时提供 Windows 可执行文件和 SHA256。也可以在本地构建：

python scripts\build_cli.py
.\_dist\frontierlab.exe --version

#生成算法可视化

最直接的用法是让 CLI 生成一个完全离线的 HTML 文件，然后双击打开。页面默认 使用中文，可切换 English，并会显示比较对象、交换方向、旧值到新值、DP 依赖、 网格坐标、图节点移动、Adapter 注释和伪代码行。

New-Item -ItemType Directory -Force _build\visual | Out-Null
moon run cmd/main -- demo insertion-sort --format html --output _build/visual/insertion-sort.html
moon run cmd/main -- demo fibonacci --format html --output _build/visual/fibonacci.html
moon run cmd/main -- demo coin-change --format html --output _build/visual/coin-change.html
moon run cmd/main -- demo knapsack --format html --output _build/visual/knapsack.html
moon run cmd/main -- demo lcs --format html --output _build/visual/lcs.html
moon run cmd/main -- demo union-find --format html --output _build/visual/union-find.html
moon run cmd/main -- demo pathfinding --format html --output _build/visual/pathfinding.html
moon run cmd/main -- demo red-black-tree --format html --output _build/visual/red-black-tree.html

如果已经有 Schema v1 JSON 轨迹，则使用：

moon run cmd/main -- render trace.json --format html --output trace.html

render_trace_svg 与 render_trace_svg_frames 在 v0.9 仅保留为旧代码兼容入口， 已经标记弃用，并计划在 v1.0 删除。新项目应选择交互 HTML；需要交换或长期存档 轨迹数据时选择 Schema v1 JSON。

#离线浏览器工具

AI Trace Clinic 是一个单文件离线页面，可导入、回放和比较轨迹，不依赖服务器、 CDN 或外部脚本：

moon run cmd/main -- playground --output _build/playground.html

生成后直接用浏览器打开 _build/playground.html。页面自带一个错误示例，用于 展示规则失败、第一次差异、状态变化和聚焦切片。

#核心 API

用途主要 API说明
记录轨迹TraceBuilder::new、record、finish把算法执行过程记录为语义事件和完整场景快照
统一诊断diagnose_trace、TraceDiagnosis::passed同时执行规则检查、参考轨迹比较和聚焦切片
调试与比较diff、breakpoint_hits、slice、first_divergence查看步骤变化、命中语义断点并定位第一次差异
JSON 协议encode_json、AlgorithmTrace::decode_json、validate读写并校验稳定的 Trace Schema v1
输出render_trace_html、render_trace_playground生成交互式离线 HTML 或诊断页面；SVG API 仅作弃用兼容

完整公开接口由 moon info 生成在 pkg.generated.mbti 中。

#独立 consumer 示例

consumer/frontierlab_consumer_demo 是一个单独的 MoonBit 项目。它通过 Mooncakes 安装 shop1111/frontierlab，不引用当前仓库中的源码，因此可以模拟 一个真正的外部使用者。

这个项目有两个作用：验证发布包确实能被其他项目安装和调用，以及提供一个完整 的集成示例。普通用户不需要运行它；安装依赖并调用上面的公开 API 即可。

发布后可用以下命令核验：

cd consumer/frontierlab_consumer_demo
moon tree
moon check --target all --deny-warn
moon test --target all --deny-warn

consumer 不会被打入 FrontierLab 的 Mooncakes 源码包，它运行时生成的 evidence/ 目录也不会提交到 Git。

#开发与验证

moon check --target all --deny-warn
moon build --target all --deny-warn
moon fmt --check
moon info
moon test --target all --deny-warn
python scripts/check_coverage.py
node scripts/check_playground.mjs
node scripts/check_renderer.mjs _build/renderer/insertion-sort.html
python scripts/validate_cli.py
moon package --list
moon package

更多资料：

#License

MIT

#
TraceError

source
pub(all) suberror TraceError {
  JsonSyntax(String)
  UnsupportedSchema(String)
  DuplicateId(String)
  DanglingReference(TargetRef)
  InvalidGraph(String)
  InvalidGrid(String)
  InvalidStep(String)
  DuplicateSummaryKey(String)
  AlreadyCompleted
  LimitExceeded(String)
} derive(Eq, 
Debug)

impl Show for TraceError

#
TraceError::message

source
fn TraceError::message(self : TraceError) -> String

#
AlgorithmReport

source
pub struct AlgorithmReport {
  algorithm : String
  reachable : Bool
  visited_count : Int
  path_length : Int
  total_cost : Int
} derive(Eq, ToJson, 
Debug)

#
AlgorithmReport::from_result

source
fn AlgorithmReport::from_result(algorithm : String, result : PathResult) -> AlgorithmReport

#
AlgorithmTrace

source
pub struct AlgorithmTrace {
  schema_version : String
  title : String
  algorithm : String
  description : String
  initial_scene : Scene
  steps : Array[AlgorithmTraceStep]
  summary : Array[TraceAttribute]
} derive(Eq, ToJson, 
Debug)

#
AlgorithmTrace::analysis_markdown

source
fn AlgorithmTrace::analysis_markdown(self : AlgorithmTrace, target_limit? : Int) -> String

#
AlgorithmTrace::analyze

source

#
AlgorithmTrace::breakpoint_hits

source
fn AlgorithmTrace::breakpoint_hits(self : AlgorithmTrace, breakpoint : TraceBreakpoint) -> Array[TraceBreakpointHit]

#
AlgorithmTrace::decode_json

source
fn AlgorithmTrace::decode_json(input : StringView, options? : TraceOptions) -> AlgorithmTrace raise TraceError

Decode and validate the stable FrontierLab schema-v1 wire format.

#
AlgorithmTrace::diff

source
fn AlgorithmTrace::diff(self : AlgorithmTrace, from_step~ : Int, to_step~ : Int) -> TraceFrameDiff raise TraceError

#
AlgorithmTrace::encode_json

source
fn AlgorithmTrace::encode_json(self : AlgorithmTrace) -> String

Encode the stable FrontierLab schema-v1 wire format.

#
AlgorithmTrace::event_counts

source
fn AlgorithmTrace::event_counts(self : AlgorithmTrace) -> Array[EventCount]

#
AlgorithmTrace::has_lint_errors

source
fn AlgorithmTrace::has_lint_errors(self : AlgorithmTrace) -> Bool

#
AlgorithmTrace::has_lint_warnings

source
fn AlgorithmTrace::has_lint_warnings(self : AlgorithmTrace) -> Bool

#
AlgorithmTrace::lint

source

Run non-throwing quality checks that complement AlgorithmTrace::validate.

#
AlgorithmTrace::lint_count

source
fn AlgorithmTrace::lint_count(self : AlgorithmTrace, severity : TraceLintSeverity) -> Int

#
AlgorithmTrace::lint_markdown

source
fn AlgorithmTrace::lint_markdown(self : AlgorithmTrace) -> String

#
AlgorithmTrace::lint_report

source
fn AlgorithmTrace::lint_report(self : AlgorithmTrace) -> String

#
AlgorithmTrace::object_usage

source
fn AlgorithmTrace::object_usage(self : AlgorithmTrace) -> Array[ObjectUsage]

#
AlgorithmTrace::slice

source
fn AlgorithmTrace::slice(self : AlgorithmTrace, center~ : Int, before? : Int, after? : Int) -> TraceCounterexample raise TraceError

#
AlgorithmTrace::summary_report

source
fn AlgorithmTrace::summary_report(self : AlgorithmTrace) -> String

#
AlgorithmTrace::target_usage

source
fn AlgorithmTrace::target_usage(self : AlgorithmTrace) -> Array[TargetUsage]

#
AlgorithmTrace::timeline

source

#
AlgorithmTrace::timeline_report

source
fn AlgorithmTrace::timeline_report(self : AlgorithmTrace) -> String

#
AlgorithmTrace::timeline_table

source
fn AlgorithmTrace::timeline_table(self : AlgorithmTrace) -> String

#
AlgorithmTrace::to_json_string

source
fn AlgorithmTrace::to_json_string(self : AlgorithmTrace) -> String

#
AlgorithmTrace::validate

source
fn AlgorithmTrace::validate(self : AlgorithmTrace, options? : TraceOptions) -> Unit raise TraceError

#
AlgorithmTraceStep

source
pub struct AlgorithmTraceStep {
  index : Int
  event : TraceEvent
  scene : Scene
  annotation : Annotation?
} derive(Eq, ToJson, 
Debug)

#
Annotation

source
pub struct Annotation {
  title : String
  body : String
  pseudocode_line : Int?
} derive(Eq, ToJson, 
Debug)

#
Annotation::new

source
fn Annotation::new(title~ : String, body~ : String, pseudocode_line? : Int) -> Annotation

#
CompareReport

source
pub struct CompareReport {
  entries : Array[AlgorithmReport]
} derive(Eq, ToJson, 
Debug)

#
ContractReport

source
pub struct ContractReport {
  report_version : String
  contract_name : String
  passed : Bool
  violations : Array[TraceViolation]
  first_failure : TraceViolation?
  counterexample : TraceCounterexample?
} derive(Eq, ToJson, 
Debug)

#
ContractReport::report

source
fn ContractReport::report(self : ContractReport) -> String

#
ContractReport::to_json_string

source
fn ContractReport::to_json_string(self : ContractReport) -> String

#
ContractReport::to_markdown

source
fn ContractReport::to_markdown(self : ContractReport) -> String

#
CostEntry

source
pub struct CostEntry {
  position : Position
  cost : Int
} derive(Eq, ToJson, 
Debug)

#
CostEntry::new

source
fn CostEntry::new(position~ : Position, cost~ : Int) -> CostEntry

#
DebugEntity

source
type DebugEntity derive(Eq, 
Debug)

#
EventCount

source
pub struct EventCount {
  name : String
  count : Int
  first_step : Int
  last_step : Int
} derive(Eq, ToJson, 
Debug)

A counted event kind in an AlgorithmTrace.

#
EventCount::new

source
fn EventCount::new(name~ : String, count? : Int, first_step? : Int, last_step? : Int) -> EventCount

#
GraphEdge

source
pub struct GraphEdge {
  id : String
  from : String
  to : String
  label : String
  directed : Bool
} derive(Eq, ToJson, 
Debug)

#
GraphEdge::new

source
fn GraphEdge::new(id~ : String, from~ : String, to~ : String, label? : String, directed? : Bool) -> GraphEdge

#
GraphNode

source
pub struct GraphNode {
  id : String
  label : String
} derive(Eq, ToJson, 
Debug)

#
GraphNode::new

source
fn GraphNode::new(id~ : String, label~ : String) -> GraphNode

#
GraphState

source
pub struct GraphState {
  id : String
  label : String
  nodes : Array[GraphNode]
  edges : Array[GraphEdge]
} derive(Eq, ToJson, 
Debug)

#
GraphState::new

source
fn GraphState::new(id~ : String, label~ : String, nodes~ : Array[GraphNode], edges~ : Array[GraphEdge]) -> GraphState raise TraceError

#
GridCellState

source
pub struct GridCellState {
  id : String
  x : Int
  y : Int
  label : String
  blocked : Bool
} derive(Eq, ToJson, 
Debug)

#
GridCellState::new

source
fn GridCellState::new(id~ : String, x~ : Int, y~ : Int, label? : String, blocked? : Bool) -> GridCellState

#
GridMap

source
pub struct GridMap {
  width : Int
  height : Int
  obstacles : Array[Position]
  weights : Array[WeightedCell]
} derive(Eq, ToJson, 
Debug)

#
GridMap::contains

source
fn GridMap::contains(self : GridMap, position : Position) -> Bool

#
GridMap::is_obstacle

source
fn GridMap::is_obstacle(self : GridMap, position : Position) -> Bool

#
GridMap::is_walkable

source
fn GridMap::is_walkable(self : GridMap, position : Position) -> Bool

#
GridMap::neighbors

source
fn GridMap::neighbors(self : GridMap, position : Position, rule : MoveRule) -> Array[Position]

#
GridMap::new

source
fn GridMap::new(width~ : Int, height~ : Int) -> GridMap raise

#
GridMap::weight_at

source
fn GridMap::weight_at(self : GridMap, position : Position) -> Int

#
GridMap::with_obstacle

source
fn GridMap::with_obstacle(self : GridMap, position : Position) -> GridMap raise

#
GridMap::with_weight

source
fn GridMap::with_weight(self : GridMap, position : Position, weight : Int) -> GridMap raise

#
GridState

source
pub struct GridState {
  id : String
  label : String
  width : Int
  height : Int
  cells : Array[GridCellState]
} derive(Eq, ToJson, 
Debug)

#
GridState::new

source
fn GridState::new(id~ : String, label~ : String, width~ : Int, height~ : Int, cells~ : Array[GridCellState]) -> GridState raise TraceError

#
Heuristic

source
pub(all) enum Heuristic {
  Manhattan
  Chebyshev
  Zero
} derive(Eq, ToJson, 
Debug)

#
Highlight

source
pub struct Highlight {
  target : TargetRef
  role : HighlightRole
} derive(Eq, ToJson, 
Debug)

#
Highlight::new

source
fn Highlight::new(target~ : TargetRef, role~ : HighlightRole) -> Highlight

#
HighlightRole

source
pub(all) enum HighlightRole {
  Current
  Candidate
  Compared
  Changed
  Visited
  Frontier
  Result
  Error
} derive(Eq, ToJson, 
Debug)

#
MoveRule

source
pub(all) enum MoveRule {
  FourDirections
  EightDirections
} derive(Eq, ToJson, 
Debug)

#
ObjectUsage

source
pub struct ObjectUsage {
  object_id : String
  object_kind : String
  appearances : Int
  max_entities : Int
  first_step : Int
  last_step : Int
} derive(Eq, ToJson, 
Debug)

Object-level usage collected across the initial scene and every step scene.

#
ObjectUsage::new

source
fn ObjectUsage::new(object_id~ : String, object_kind~ : String, appearances? : Int, max_entities? : Int, first_step? : Int, last_step? : Int) -> ObjectUsage

pub struct ParentLink {
  child : Position
  parent : Position
} derive(Eq, ToJson, 
Debug)

#
ParentLink::new

source
fn ParentLink::new(child~ : Position, parent~ : Position) -> ParentLink

#
PathResult

source
pub struct PathResult {
  reachable : Bool
  path : Array[Position]
  cost : Int
  visited_count : Int
} derive(Eq, ToJson, 
Debug)

#
PathResult::found

source
fn PathResult::found(path~ : Array[Position], cost~ : Int, visited_count~ : Int) -> PathResult

#
PathResult::not_found

source
fn PathResult::not_found(visited_count~ : Int) -> PathResult

#
Position

source
pub struct Position {
  x : Int
  y : Int
} derive(Eq, ToJson, 
Debug)

#
Position::new

source
fn Position::new(x~ : Int, y~ : Int) -> Position

#
RedBlackTreeOperation

source
pub(all) enum RedBlackTreeOperation {
  Insert(Int)
  Find(Int)
} derive(Eq, ToJson, 
Debug)

One operation accepted by the red-black-tree trace adapter.

#
Scene

source
pub struct Scene {
  objects : Array[SceneObject]
  highlights : Array[Highlight]
} derive(Eq, ToJson, 
Debug)

#
Scene::new

source
fn Scene::new(objects~ : Array[SceneObject], highlights? : Array[Highlight]) -> Scene raise TraceError

#
SceneObject

source
pub(all) enum SceneObject {
  Sequence(SequenceState)
  Sets(SetState)
  Graph(GraphState)
  Grid(GridState)
} derive(Eq, ToJson, 
Debug)

#
SearchTrace

source
pub struct SearchTrace {
  result : PathResult
  steps : Array[TraceStep]
} derive(Eq, ToJson, 
Debug)

#
SearchTrace::new

source
fn SearchTrace::new(result~ : PathResult, steps~ : Array[TraceStep]) -> SearchTrace

#
SequenceItem

source
pub struct SequenceItem {
  id : String
  value : String
} derive(Eq, ToJson, 
Debug)

#
SequenceItem::new

source
fn SequenceItem::new(id~ : String, value~ : String) -> SequenceItem

#
SequenceState

source
pub struct SequenceState {
  id : String
  label : String
  items : Array[SequenceItem]
} derive(Eq, ToJson, 
Debug)

#
SequenceState::new

source
fn SequenceState::new(id~ : String, label~ : String, items~ : Array[SequenceItem]) -> SequenceState

#
SetGroup

source
pub struct SetGroup {
  id : String
  label : String
  members : Array[String]
} derive(Eq, ToJson, 
Debug)

#
SetGroup::new

source
fn SetGroup::new(id~ : String, label~ : String, members~ : Array[String]) -> SetGroup

#
SetState

source
pub struct SetState {
  id : String
  label : String
  groups : Array[SetGroup]
} derive(Eq, ToJson, 
Debug)

#
SetState::new

source
fn SetState::new(id~ : String, label~ : String, groups~ : Array[SetGroup]) -> SetState

#
SortTraceItem

source
pub struct SortTraceItem {
  id : String
  value : Int
  label : String
} derive(Eq, ToJson, 
Debug)

One stable value in a sortable sequence trace.

#
SortTraceItem::new

source
fn SortTraceItem::new(id~ : String, value~ : Int, label? : String) -> SortTraceItem

#
TargetRef

source
pub struct TargetRef {
  object_id : String
  entity_id : String?
} derive(Eq, ToJson, 
Debug, 
FromJson)

A scoped reference to either a scene object or one entity inside it.

#
TargetRef::entity

source
fn TargetRef::entity(object_id : String, entity_id : String) -> TargetRef

#
TargetRef::object

source
fn TargetRef::object(object_id : String) -> TargetRef

#
TargetUsage

source
pub struct TargetUsage {
  object_id : String
  entity_id : String?
  references : Int
  event_references : Int
  highlight_references : Int
  first_step : Int
  last_step : Int
  event_names : Array[String]
  highlight_roles : Array[String]
} derive(Eq, ToJson, 
Debug)

Target-level references observed in semantic events and visual highlights.

#
TargetUsage::new

source
fn TargetUsage::new(object_id~ : String, entity_id? : String, references? : Int, event_references? : Int, highlight_references? : Int, first_step? : Int, last_step? : Int, event_names? : Array[String], highlight_roles? : Array[String]) -> TargetUsage

#
TraceAttribute

source
pub struct TraceAttribute {
  key : String
  value : String
} derive(Eq, ToJson, 
Debug)

A stable key/value attribute used by custom events and summaries.

#
TraceAttribute::new

source
fn TraceAttribute::new(key~ : String, value~ : String) -> TraceAttribute

#
TraceBreakpoint

source
pub struct TraceBreakpoint {
  event_kind : String
  target : TargetRef?
  role : String
  changed_only : Bool
} derive(Eq, ToJson, 
Debug)

#
TraceBreakpoint::new

source
fn TraceBreakpoint::new(event_kind? : String, target? : TargetRef, role? : String, changed_only? : Bool) -> TraceBreakpoint

#
TraceBreakpointHit

source
pub struct TraceBreakpointHit {
  step : Int
  event_kind : String
  targets : Array[TargetRef]
  changes : Array[TraceChange]
  reason : String
} derive(Eq, ToJson, 
Debug)

#
TraceBuilder

source
pub struct TraceBuilder {
  title : String
  algorithm : String
  description : String
  initial_scene : Scene
  steps : Array[AlgorithmTraceStep]
  options : TraceOptions
  completed : Bool
} derive(
Debug)

Mutable recorder that stores immutable scene snapshots.

#
TraceBuilder::finish

source
fn TraceBuilder::finish(self : TraceBuilder, summary? : Array[TraceAttribute]) -> AlgorithmTrace raise TraceError

#
TraceBuilder::new

source
fn TraceBuilder::new(title~ : String, algorithm~ : String, description? : String, initial_scene~ : Scene, options? : TraceOptions) -> TraceBuilder raise TraceError

#
TraceBuilder::record

source
fn TraceBuilder::record(self : TraceBuilder, event~ : TraceEvent, scene~ : Scene, annotation? : Annotation) -> Unit raise TraceError

#
TraceChange

source
pub struct TraceChange {
  kind : TraceChangeKind
  target : TargetRef
  before_value : String
  after_value : String
  before_index : Int
  after_index : Int
} derive(Eq, ToJson, 
Debug)

#
TraceChange::new

source
fn TraceChange::new(kind~ : TraceChangeKind, target~ : TargetRef, before_value? : String, after_value? : String, before_index? : Int, after_index? : Int) -> TraceChange

#
TraceChangeKind

source
pub(all) enum TraceChangeKind {
  Added
  Removed
  Updated
  Moved
  HighlightAdded
  HighlightRemoved
} derive(Eq, ToJson, 
Debug)

#
TraceContract

source
pub struct TraceContract {
  name : String
  description : String
  checker : (AlgorithmTrace) -> Array[TraceViolation]
}

An extensible semantic contract backed by a pure MoonBit checker callback.

#
TraceContract::check

source

#
TraceContract::new

source
fn TraceContract::new(name~ : String, description~ : String, checker~ : (AlgorithmTrace) -> Array[TraceViolation]) -> TraceContract

#
TraceCounterexample

source
pub struct TraceCounterexample {
  original_title : String
  original_start : Int
  original_focus : Int
  original_end : Int
  focus_step : Int
  trace : AlgorithmTrace
} derive(Eq, ToJson, 
Debug)

#
TraceCounterexample::to_json_string

source
fn TraceCounterexample::to_json_string(self : TraceCounterexample) -> String

#
TraceDiagnosis

source
pub struct TraceDiagnosis {
  contract_report : ContractReport
  divergence : TraceDivergence?
  focus_step : Int
  transition_diff : TraceFrameDiff?
  reference_diff : TraceFrameDiff?
  focused_slice : TraceCounterexample?
} derive(Eq, ToJson, 
Debug)

The authoritative result of combining a semantic contract with an optional reference trace.

#
TraceDiagnosis::passed

source
fn TraceDiagnosis::passed(self : TraceDiagnosis) -> Bool

Return whether both the semantic contract and optional reference agree.

#
TraceDivergence

source
pub struct TraceDivergence {
  step : Int
  kind : TraceDivergenceKind
  message : String
  expected_event : String
  actual_event : String
  scene_diff : TraceFrameDiff?
} derive(Eq, ToJson, 
Debug)

#
TraceDivergence::to_json_string

source
fn TraceDivergence::to_json_string(self : TraceDivergence) -> String

#
TraceDivergenceKind

source
pub(all) enum TraceDivergenceKind {
  EventMismatch
  SceneMismatch
  ExpectedEnded
  ActualEnded
} derive(Eq, ToJson, 
Debug)

#
TraceEvent

source
pub(all) enum TraceEvent {
  Initialize
  Compare(Array[TargetRef])
  Swap(TargetRef, TargetRef)
  Visit(TargetRef)
  Update(TargetRef, String)
  Union(TargetRef, TargetRef)
  Relax(TargetRef, TargetRef, String)
  Complete
  Custom(String, Array[TraceAttribute])
} derive(Eq, ToJson, 
Debug)

The semantic reason why an algorithm produced a new scene.

#
TraceFrameDiff

source
pub struct TraceFrameDiff {
  from_step : Int
  to_step : Int
  changes : Array[TraceChange]
} derive(Eq, ToJson, 
Debug)

#
TraceFrameDiff::is_empty

source
fn TraceFrameDiff::is_empty(self : TraceFrameDiff) -> Bool

#
TraceFrameDiff::report

source
fn TraceFrameDiff::report(self : TraceFrameDiff) -> String

#
TraceFrameDiff::to_json_string

source
fn TraceFrameDiff::to_json_string(self : TraceFrameDiff) -> String

#
TraceLintIssue

source
pub struct TraceLintIssue {
  severity : TraceLintSeverity
  code : String
  message : String
  step : Int
} derive(Eq, ToJson, 
Debug)

A non-throwing quality observation for a trace document.

#
TraceLintIssue::is_error

source
fn TraceLintIssue::is_error(self : TraceLintIssue) -> Bool

#
TraceLintIssue::is_info

source
fn TraceLintIssue::is_info(self : TraceLintIssue) -> Bool

#
TraceLintIssue::is_warning

source
fn TraceLintIssue::is_warning(self : TraceLintIssue) -> Bool

#
TraceLintIssue::line

source
fn TraceLintIssue::line(self : TraceLintIssue) -> String

#
TraceLintIssue::markdown_row

source
fn TraceLintIssue::markdown_row(self : TraceLintIssue) -> String

#
TraceLintIssue::new

source
fn TraceLintIssue::new(severity~ : TraceLintSeverity, code~ : String, message~ : String, step? : Int) -> TraceLintIssue

#
TraceLintIssue::severity_name

source
fn TraceLintIssue::severity_name(self : TraceLintIssue) -> String

#
TraceLintSeverity

source
pub(all) enum TraceLintSeverity {
  Info
  Warning
  Error
} derive(Eq, ToJson, 
Debug)

Severity for lightweight trace quality checks.

#
TraceOptions

source
pub struct TraceOptions {
  max_steps : Int
  max_entities_per_scene : Int
} derive(Eq, ToJson, 
Debug, 
FromJson)

#
TraceOptions::default

source
fn TraceOptions::default() -> TraceOptions

#
TraceOptions::new

source
fn TraceOptions::new(max_steps? : Int, max_entities_per_scene? : Int) -> TraceOptions raise TraceError

#
TraceStats

source
pub struct TraceStats {
  title : String
  algorithm : String
  step_count : Int
  completed : Bool
  event_counts : Array[EventCount]
  object_usage : Array[ObjectUsage]
  target_usage : Array[TargetUsage]
  initial_object_count : Int
  max_objects_per_scene : Int
  max_entities_per_scene : Int
  summary_count : Int
  annotation_count : Int
  custom_event_count : Int
  highlight_count : Int
} derive(Eq, ToJson, 
Debug)

Summary of a full trace document, suitable for docs, CLI output, or CI smoke checks before rendering.

#
TraceStats::event_count

source
fn TraceStats::event_count(self : TraceStats, name : String) -> Int

#
TraceStats::event_table

source
fn TraceStats::event_table(self : TraceStats) -> String

Render the event section of TraceStats as a Markdown table.

#
TraceStats::object_count

source
fn TraceStats::object_count(self : TraceStats, object_id : String) -> Int

#
TraceStats::object_table

source
fn TraceStats::object_table(self : TraceStats) -> String

Render the object section of TraceStats as a Markdown table.

#
TraceStats::summary_report

source
fn TraceStats::summary_report(self : TraceStats) -> String

#
TraceStats::target_count

source
fn TraceStats::target_count(self : TraceStats, object_id : String, entity_id? : String) -> Int

#
TraceStats::target_table

source
fn TraceStats::target_table(self : TraceStats, limit? : Int) -> String

Render the most referenced targets as a Markdown table.

#
TraceStats::to_markdown

source
fn TraceStats::to_markdown(self : TraceStats, target_limit? : Int) -> String

Render the full analysis as Markdown for READMEs, reports, and CI artifacts.

#
TraceStats::top_targets

source
fn TraceStats::top_targets(self : TraceStats, limit? : Int) -> Array[TargetUsage]

#
TraceStep

source
pub struct TraceStep {
  current : Position?
  frontier : Array[Position]
  visited : Array[Position]
  cost : Array[CostEntry]
  parent : Array[ParentLink]
} derive(Eq, ToJson, 
Debug)

#
TraceStep::new

source
fn TraceStep::new(current~ : Position?, frontier~ : Array[Position], visited~ : Array[Position], cost~ : Array[CostEntry], parent~ : Array[ParentLink]) -> TraceStep

#
TraceTimelineEntry

source
pub struct TraceTimelineEntry {
  step : Int
  event_name : String
  target_count : Int
  object_count : Int
  entity_count : Int
  highlight_count : Int
  annotation_title : String
  completed : Bool
} derive(Eq, ToJson, 
Debug)

A compact row describing one renderable point in a trace timeline.

#
TraceTimelineEntry::label

source
fn TraceTimelineEntry::label(self : TraceTimelineEntry) -> String

#
TraceTimelineEntry::markdown_row

source
fn TraceTimelineEntry::markdown_row(self : TraceTimelineEntry) -> String

#
TraceTimelineEntry::new

source
fn TraceTimelineEntry::new(step~ : Int, event_name~ : String, target_count~ : Int, object_count~ : Int, entity_count~ : Int, highlight_count~ : Int, annotation_title? : String, completed? : Bool) -> TraceTimelineEntry

#
TraceViolation

source
pub struct TraceViolation {
  contract : String
  code : String
  severity : TraceViolationSeverity
  step : Int
  targets : Array[TargetRef]
  message : String
  evidence : Array[TraceAttribute]
} derive(Eq, ToJson, 
Debug)

#
TraceViolation::new

source
fn TraceViolation::new(contract~ : String, code~ : String, severity? : TraceViolationSeverity, step? : Int, targets? : Array[TargetRef], message~ : String, evidence? : Array[TraceAttribute]) -> TraceViolation

#
TraceViolationSeverity

source
pub(all) enum TraceViolationSeverity {
  Warning
  Error
} derive(Eq, ToJson, 
Debug)

#
UnionOperation

source
pub struct UnionOperation {
  left : Int
  right : Int
  label : String
} derive(Eq, ToJson, 
Debug)

One union operation for the Union-Find trace adapter.

#
UnionOperation::new

source
fn UnionOperation::new(left~ : Int, right~ : Int, label? : String) -> UnionOperation

#
WeightedCell

source
type WeightedCell derive(Eq, ToJson, 
Debug)

#
astar

source
fn astar(grid : GridMap, start~ : Position, goal~ : Position, rule? : MoveRule, heuristic? : Heuristic) -> PathResult raise

#
astar_trace

source
fn astar_trace(grid : GridMap, start~ : Position, goal~ : Position, rule? : MoveRule, heuristic? : Heuristic) -> SearchTrace raise

#
bfs

source
fn bfs(grid : GridMap, start~ : Position, goal~ : Position, rule? : MoveRule) -> PathResult raise

#
bfs_trace

source
fn bfs_trace(grid : GridMap, start~ : Position, goal~ : Position, rule? : MoveRule) -> SearchTrace raise

#
coin_change_dp_trace

source
fn coin_change_dp_trace(coins : Array[Int], amount : Int, title? : String, object_id? : String, label? : String, options? : TraceOptions) -> AlgorithmTrace raise TraceError

Build a one-dimensional minimum-coin-change dynamic-programming trace.

#
compare_algorithms

source
fn compare_algorithms(grid : GridMap, start~ : Position, goal~ : Position, rule? : MoveRule, heuristic? : Heuristic) -> CompareReport raise

#
debug_report_version

source
let debug_report_version : String

Stable version marker for machine-readable debugger reports.

#
diagnose_trace

source
fn diagnose_trace(actual : AlgorithmTrace, contract~ : TraceContract, expected? : AlgorithmTrace) -> TraceDiagnosis

Diagnose an actual trace with a contract and an optional reference trace.

The focus is the earliest non-negative contract failure or divergence. transition_diff describes the actual transition into that focus, while reference_diff compares expected and actual state at the focus.

#
dijkstra

source
fn dijkstra(grid : GridMap, start~ : Position, goal~ : Position, rule? : MoveRule) -> PathResult raise

#
dijkstra_trace

source
fn dijkstra_trace(grid : GridMap, start~ : Position, goal~ : Position, rule? : MoveRule) -> SearchTrace raise

#
export_ascii

source
fn export_ascii(grid : GridMap, start~ : Position, goal~ : Position, trace? : SearchTrace) -> String

#
export_svg

source
fn export_svg(grid : GridMap, start~ : Position, goal~ : Position, trace? : SearchTrace, cell_size? : Int) -> String

#
faulty_insertion_sort_demo_trace

source
fn faulty_insertion_sort_demo_trace() -> AlgorithmTrace raise

Build an intentionally faulty trace for debugger and contract demos.

#
fibonacci_dp_trace

source
fn fibonacci_dp_trace(n : Int, title? : String, object_id? : String, label? : String, options? : TraceOptions) -> AlgorithmTrace raise TraceError

Build a Fibonacci dynamic-programming trace for F(n).

#
first_divergence

source
fn first_divergence(expected : AlgorithmTrace, actual : AlgorithmTrace) -> TraceDivergence?

#
grid_path_contract

source
fn grid_path_contract(object_id~ : String) -> TraceContract

#
heuristic_distance

source
fn heuristic_distance(kind : Heuristic, from : Position, to : Position) -> Int

#
insertion_sort_demo_trace

source
fn insertion_sort_demo_trace(values : Array[Int]) -> AlgorithmTrace raise

Build the insertion-sort trace used by the bundled demo and CLI.

#
insertion_sort_int_contract

source
fn insertion_sort_int_contract(object_id~ : String) -> TraceContract

#
insertion_sort_items_trace

source
fn insertion_sort_items_trace(items : Array[SortTraceItem], title? : String, object_id? : String, label? : String) -> AlgorithmTrace raise TraceError

Build an insertion-sort trace while preserving caller-provided stable item ids. Stable ids make animated swaps and external annotations deterministic.

#
insertion_sort_trace

source
fn insertion_sort_trace(values : Array[Int], title? : String, object_id? : String, label? : String) -> AlgorithmTrace raise TraceError

Build a reusable insertion-sort trace from plain integer values.

#
lcs_dp_trace

source
fn lcs_dp_trace(left : String, right : String, title? : String, object_id? : String, label? : String, options? : TraceOptions) -> AlgorithmTrace raise TraceError

Build a two-dimensional longest-common-subsequence trace.

#
pathfinding_demo_trace

source
fn pathfinding_demo_trace() -> AlgorithmTrace raise

Build the A* flagship trace used by the bundled demo and CLI.

#
project_name

source
let project_name : String

Human-readable project name.

#
red_black_tree_trace

source
fn red_black_tree_trace(operations : Array[RedBlackTreeOperation], title? : String, object_id? : String, label? : String, options? : TraceOptions) -> AlgorithmTrace raise TraceError

Build a red-black-tree trace with insertion balancing and lookup paths.

#
render_trace_html

source
fn render_trace_html(trace : AlgorithmTrace) -> String

Render a trace as a self-contained offline HTML player.

#
render_trace_playground

source
fn render_trace_playground() -> String raise TraceError

Render the self-contained AI Trace Clinic.

The page intentionally has no framework, server, or external asset. Its default evidence mirrors fixtures/agent-traces: a selection-sort trace whose stale-index swap first diverges at step 10.

#
render_trace_svg

source
#deprecated("Legacy static renderer; use render_trace_html or Schema v1 JSON. This API will be removed in v1.0.")
fn render_trace_svg(trace : AlgorithmTrace, step? : Int, width? : Int) -> String raise

Render one trace frame as a deterministic, standalone SVG document.

#
render_trace_svg_frames

source
#deprecated("Legacy static renderer; use render_trace_html or Schema v1 JSON. This API will be removed in v1.0.")
fn render_trace_svg_frames(trace : AlgorithmTrace, width? : Int) -> Array[String] raise

Render every recorded step. An empty trace yields its initial scene.

#
search_trace_to_algorithm_trace

source
fn search_trace_to_algorithm_trace(grid : GridMap, start~ : Position, goal~ : Position, algorithm~ : String, trace~ : SearchTrace) -> AlgorithmTrace raise

Convert a legacy path-search trace into the generic visualization protocol.

#
sequence_transition_contract

source
fn sequence_transition_contract(object_id~ : String) -> TraceContract

#
sorted_int_sequence_contract

source
fn sorted_int_sequence_contract(object_id~ : String) -> TraceContract

Check stable sequence transitions and a nondecreasing integer result.

Unlike insertion_sort_int_contract, this name is algorithm-neutral and is suitable for selection sort, merge sort, agent-generated traces, and other sorting implementations.

#
union_find_demo_trace

source
fn union_find_demo_trace() -> AlgorithmTrace raise

Build the Union-Find trace used by the bundled demo and CLI.

#
union_find_trace

source
fn union_find_trace(size : Int, operations : Array[UnionOperation], title? : String, object_id? : String, label? : String, compress_paths? : Bool) -> AlgorithmTrace raise TraceError

Build a reusable Union-Find trace from a size and an ordered operation list.

#
zero_one_knapsack_dp_trace

source
fn zero_one_knapsack_dp_trace(weights : Array[Int], values : Array[Int], capacity : Int, title? : String, object_id? : String, label? : String, options? : TraceOptions) -> AlgorithmTrace raise TraceError

Build a two-dimensional 0/1-knapsack dynamic-programming trace.

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io