Skip to content

Checks Surface

Jump to bottom
Chazona Baum edited this page Jun 24, 2026 · 1 revision

Relevant source files

The Checks Surface provides a detailed observability layer for the job-fetch pipeline. It allows users to monitor the execution of automated runs, inspect the step-by-step telemetry of scraping and LLM tasks, and track resource consumption (ScrapingBee credits and OpenRouter USD costs).

Overview

The surface consists of two primary views:

  1. Checks List: A ledger of all historical and active pipeline runs (e.g., job_check, job_detail) with high-level rollups of status and cost.
  2. Check Detail: A deep-dive into a single run, displaying a chronological table of Step entities, including cache performance and error logs.

The frontend communicates with the Rust backend via Tauri commands to read check data stored as Markdown files in the vault's checks/ directory.

Data Flow: Pipeline to UI

The pipeline's telemetry is persisted to the vault by the backend. The frontend synchronizes with these updates using a combination of reactive stores and event listeners.

Component Role
checksStore Svelte state managing the list of CheckSummary objects.
onRunStep Listener for incremental pipeline progress events.
onRunFinished Listener for terminal pipeline events to trigger a final reload.
getCheck Fetches the full Check object (including steps) for a specific ID.

Sources:src/routes/checks/+page.svelte#18-36src/lib/check.ts#81-89

The Checks Store & Spend Calculation

The checksStore (defined in src/lib/checks.svelte) is the central repository for run summaries. Because the pipeline's writes to check files are "self-writes" (suppressed by the vault watcher to prevent infinite loops), the store manually reloads when the pipeline emits events.

Cost Rollups

Costs are tracked in two distinct units:

  • Credits: Integer units consumed by ScrapingBee.
  • USD Micro: Micro-dollars (1,000,000 = $1.00) consumed by OpenRouter, stored as integers to maintain precision.

The runSpend and totalSpend functions in src/lib/spend.ts calculate these rollups by inspecting the class of each step.

Run Spend Logic:

  • If step.class === "scrape", the cost is added to credits.
  • If step.class === "llm" or "llm+web", the cost is added to usdMicro.

Sources:src/lib/spend.ts#11-20src/lib/check.ts#61-62src/routes/checks/+page.svelte#43-48

Check Detail & Telemetry

The Check Detail page (src/routes/checks/[id]/+page.svelte) renders the full Check object. It provides a steps-table that visualizes the execution flow of the pipeline.

Step Status Styling

Rows in the step table are styled based on their terminal state. Specifically, steps with a status of "failed" receive the .steps-row--failed class, which applies a semantic danger-soft background.

Cache Activity Formatting

For LLM steps, the UI displays prompt caching performance using the formatCache utility. This identifies how many tokens were read from or written to the OpenRouter/provider cache.

Scenario Output Example
Cold Cache (First call) · cache 7,000 write
Cache Hit · cache 6,656 read
Partial Hit · cache 6,656 read · 7,000 write

Sources:src/lib/check.ts#32-44src/routes/checks/[id]/+page.svelte:60-69, src/lib/styles/layout/checks.css#105-107

Technical Diagrams

System Entity Mapping: Checks Surface

This diagram maps the UI concepts to the underlying TypeScript interfaces and Rust-proxied data structures.

flowchart LR
    subgraph subGraph2 ["Persistence (Vault)"]
        I["/checks/*.md"]
    end
    subgraph subGraph1 ["Code Entity Space (TypeScript)"]
        D["CheckSummary #91;src/lib/check.ts#93;"]
        E["Step #91;src/lib/check.ts#93;"]
        F["Spend #91;src/lib/spend.ts#93;"]
        G["checksStore #91;src/lib/checks.svelte#93;"]
        H["getCheck() #91;src/lib/check.ts#93;"]
    end
    subgraph subGraph0 ["Natural Language Space"]
        A["Run Ledger"]
        B["Step Telemetry"]
        C["Financial Rollup"]
    end
    A --> D
    B --> E
    C --> F
    D --> G
    E --> H
    G --> I
    H --> I
Loading

Sources:src/lib/check.ts#7-79src/lib/spend.ts#5-8src/routes/checks/+page.svelte#4-12

Check Detail Data Flow

The sequence of events when a user views a specific check run and the pipeline is active.

sequenceDiagram
    participant UI as +page.svelte (Detail)
    participant Pipe as Pipeline (Rust)
    participant Store as checksStore
    participant API as Tauri Bridge (invoke)
    Note over UI: User navigates to /checks/[id]
    UI->>API: getCheck(vault | id)
    API-->>UI: Return Check { steps: Step[] }
    Note over Pipe: Pipeline completes a step
    Pipe->>UI: Emit "record:step" event
    UI->>Store: reload()
    Store->>API: list_checks
    API-->>Store: Update summaries
    Note over UI: Reactive $derived(spend) updates
    UI->>UI: runSpend(check.steps)
Loading

Sources:src/routes/checks/[id]/+page.svelte:17-30, src/routes/checks/+page.svelte#18-36src/lib/spend.ts#11-20

Implementation Details

UI Components and Styling

The surface uses semantic <table> elements rather than CSS grids to handle the dense telemetry data.

  • Status Pills: The .checks__status class uses semantic tokens (e.g., --good-soft, --danger-soft) to color-code statuses like ok, partial, complete, and failed.
  • Precision Formatting: LLM costs are formatted with sub-cent precision using (cost / 1e6).toFixed(4) to reflect the micro-dollar storage format.

Functions and Logic

Function File Description
formatCache src/lib/check.ts#32 Converts cache_read_tokens and cache_write_tokens into a human-readable string.
runSpend src/lib/spend.ts#11 Iterates through Step[] and aggregates costs based on the class field.
fmtCost src/routes/checks/[id]/+page.svelte:12 Local helper to append "cr" for scraping or "$" for LLM costs in the UI.
listChecks src/lib/check.ts#82 Invokes the list_checks Tauri command to retrieve all run summaries.

Sources:src/lib/check.ts#32-44src/lib/spend.ts#11-20src/routes/checks/[id]/+page.svelte:12-15, src/lib/styles/layout/checks.css#54-73

Clone this wiki locally