🥮 mooncakes.io

    frontierlab

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

    algorithm
    trace
    visualization
    education
    html
    debugger
    Download zip
    Author
    Version
    0.9.1
    License
    MIT
    Repository
    Last updated
    last month
    Downloads
    43

    Dependencies

    #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