Run the engine
Three ways to put claims through the rule engine. Each one executes the same runtime and publishes the same report set — they differ only in where the claims come from.
Every run uses the rule pack and data source named in the bar above. Artifacts, the log, and KPI of any finished run are in the sidebar under Inspect.
Select rules to include
Choose which rules from rules/scrubber-core.yaml go into this run. The selection compiles into a filtered test-pack.yaml — same rule bodies, only the checked IDs kept in the plan.
Data source
Point the run at a repository claims corpus or the server-configured read-only PostgreSQL source. The backend validates source availability here and performs normalization during execution.
Claims corpus (files)
JSON claim files under claims/json/<client>/<date>/<NPI>, or a flat directory loaded as one client group.
PostgreSQL claim source
Read-only --pg-source config against an organization-scoped Postgres database (e.g. the HSA / Neon corpus).
Corpus preset
Evidence folders (not a separate source input)
Prior-payer remittance dates for COB rules such as SCR-171 and PRP-041. Optional — omit to leave those rules under-evidenced.
Captured 271 response fixtures for the coverage-span replay (PRP-001a). Test evidence, not a live eligibility bridge.
Batch run
Run the selected rule pack against the configured corpus, or drop in a single claim JSON file to spot-check it without touching the corpus.
Run history
| Run | Started | Source | Rules | Duration | Result |
|---|
Single claim
Evaluates the 42-rule selection from Rule Pack against one claim JSON — no corpus, no evidence folders. Useful for spot-checking a payer's claim without a full run.
Accepts one .json file shaped like a record from claims-era/json/<client>/claims.
Claim file run
Upload one JSON file holding a single claim or a whole batch, pick the claims worth testing, choose the rules to run them against, then execute and read the outcome claim by claim. The file is never written to disk — the browser keeps it and posts it with the run.
One .json file — a single claim object, or an array of claims in either the raw claimHeader shape or canonical ClaimFacts. The server normalizes it and returns one row per claim.
Run failed
Rules that fired
Batch summary
/api/claim-files/parse and executes through /api/claim-files/run, which evaluates the selected claims with the same BatchRunner a data-source run uses. Uploaded claims are not persisted.Manual test cases
Run one rule against its scripted scenarios in tests/manual-tests/cases/<rule>/*.case.yaml instead of the full corpus — for isolating a single fix. Each case runs through klaim test-case.
Evaluates one claim file against the rule selection made on the Rule Pack screen — no corpus, no case manifest, nothing written to tests/manual-tests.
The server detects the format: claim JSON runs through the production runtime, EDI is reported against the engine's own normalization support.
Accepts .json claim records, or .edi / .837 / .x12 / .txt X12 files.
Rules with manual cases
Cases for SCR-152b
Subscriber State Validity — 4 scripted scenarios
Recent runs
| Run | Started | Rule | Case | Outcome | Status |
|---|
/api/cases, /api/cases/run, and /api/history. Results mirror the klaim test-case CLI. Uploaded files run through /api/test-runs/upload, which detects JSON vs. EDI server-side.Claim inspector
Read a claim the way the engine reads it. Search the corpus, drop in a file, or open the claims behind a finished run — then compare the normalized ClaimFacts against the source record side by side. Nothing here executes rules or writes anything to disk.
Corpus path
One .json file — a single claim or an array, in either the raw claimHeader shape or canonical ClaimFacts. The browser holds the bytes and posts them per request; the file is never written to disk.
Claim file run held in this session
Finished corpus runs
A corpus run records outcomes against each claim's position in discovery order. Opening one re-indexes its source and joins the two, which only holds while the corpus is unchanged — the inspector says so when it cannot line them up.Choose a source above, then select a claim from the list to see its parties, service lines, diagnoses, and money — plus the source JSON and the normalized facts.
/api/claims/index, reads one claim through /api/claims/detail, and joins run outcomes through /api/test-runs/{run_id}/claims. Normalization runs server-side through the same crates a test run uses, so what you read here is exactly what the rules see.Test artifacts
Every execution — a corpus test run, a claim-file run, a single claim, or a manual case — is registered here with the report it published, its PHI-safe result record, and its captured log. Reports are the same atomically published set klaim run --kpi-report-dir writes.
Log viewer
The operational log the engine emitted during the selected run — PHI-redacted JSON events in the format klaim writes to stderr — with the filter, search, and detail model of tools/log-viewer.html. Open a CLI log file or paste one to read it the same way.
Paste JSON log lines
| Time | Level | Target | Metadata | Message | Elapsed |
|---|
Performance & KPI
Aggregate KPI, timing, candidate reduction, and outcome mix of the selected run, read from the summary.json, outcomes-summary.json, and performance-summary.json it published.
Latency percentiles (per claim)
Candidate reduction
Decision mix
Run telemetry
Top fired rules
Slowest rules (mean invocation time)
Rule engine settings
Defaults passed to every klaim run this console launches. Per-run overrides on the Batch Run screen take precedence.
Rule catalog
The pack every screen starts from. Changing it reloads the Rule Pack screen from the new catalog and re-selects its active rules, so any run launched afterwards uses it.
Execution
Reference data
Reporting & artifacts
logs/run.jsonl and opens in the Log Viewer; a capture stops keeping lines after 100,000 and says so in its last line. Use debug for a handful of claims, not a corpus.
Auth (optional)
/api/rule-packs and drives every run this console launches. The remaining fields mirror real klaim run flags (see docs/guides/02-user-guide.md §17 CLI Reference) but are not yet persisted or passed to a process.Help
Where this console's workflows come from, and where to go deeper. Pick a page from the submenu.
CLI launch options
This console launches the same runner the CLI does, so every option below is what a screen here captures before a run. Authoritative reference: klaim help and docs/guides/02-user-guide.md §17.
klaim parse [--output json] [--mode test|debug|production] <file>
klaim check [--mode test|debug|production] [--profile <id>] <file>
klaim audit [--output human|json] [--mode test|debug|production] [--profile <id>]
[--claims <dir> | --claim <file>] [--snapshot <snapshot.json>]
[--data-root <dir>] [--evaluation-date YYYY-MM-DD] [--fail-on-warnings]
[--max-global-ratio <0..1>] [--max-lines <n>] [--max-pair-invocations <n>]
<rule_file>
klaim run [--mode debug] [--profile <id>] [--claims <dir>] [--claim <file>]
[--preprocess <file>] [--file-batch-size <positive integer>]
[--evaluation-date YYYY-MM-DD] [--reference-manifest <path>]
[--reference-as-of YYYY-MM-DD] [--reference-legacy-auto-load] [--data-root <dir>]
[--kpi-report-dir <dir>] [--performance-audit off|summary|detailed]
[--performance-audit-output <dir>] [--performance-audit-fail-on-warning]
[performance audit thresholds] [--split-by <dim1,dim2>] [--aging <b1,b2>]
[--payer <code1,code2>] [--tenant-config <file>] [--provider <id>]
[--feedback-token-key-file <file>] [--include-claim-id]
[--auth-config <file>] [--auth-token <token>] [--require-auth]
[--rule <id>] [--domain <name>] [--phase <name>] <rule_file>
klaim test-case <case.yaml> [--record <dir>] [--tested-by <name>]
klaim trace [--rule-id <id>] [--profile <id>] <rule_file>
klaim plan show <pack> [--profile <id>] [--format human|json]
klaim plan hash <pack> [--profile <id>] [--kind plan|schedule|both] [--format plain|json]
klaim plan explain <pack> [--profile <id>] (--rule <id> | --why-before <left> <right>)
[--format human|json]
klaim plan diff <left-pack> <right-pack> [--left-profile <id>] [--right-profile <id>]
[--format human|json] [--check]
klaim preprocess --stats [--db <path>]
klaim preprocess --clear-log [--db <path>]
klaim help
Modes (--mode): test deterministic, no external calls, snapshot-compatible
debug step-by-step tracing, verbose I/O at every stage
production optimized, minimal logging, PHI-safe (default)
What each command does
| Command | Purpose | Key options |
|---|---|---|
parse | Parse and validate a rule file; optional canonical JSON output. | --output json, --mode |
check | Validate a rule file against the pack contract. | --mode, --profile |
audit | Architecture / publication audit of a rule pack; can run over claims. | --output human|json, --claims/--claim, --snapshot, --data-root, --evaluation-date, --fail-on-warnings, invocation limits |
run | Execute claims through the compiled pack — the command this console fronts. | Every flag below |
test-case | Execute one scripted manual case for one selected rule; immutable artifacts plus ledger.csv. | --record <dir>, --tested-by <name> |
trace | Step-by-step evaluation trace for one rule. | --rule-id, --profile |
plan | Plan inspection — show, hash, explain, diff. | --format, --profile, --check |
preprocess | Processing-ledger admin. | --stats, --clear-log, --db |
help | Print this usage. | — |
klaim run launch flags
| Flag | Effect |
|---|---|
--mode | test / debug / production (production is the default). |
--profile <id> | Execution profile for plan compilation. |
--claims <dir> | Batch claims directory — all, date, or NPI folder levels. |
--claim <file> | Single claim JSON (raw claimHeader or canonical ClaimFacts). |
--preprocess <file> | Preprocessor config; pairs with --preprocess-output, --preprocess-only, --processing-db, --dry-run. |
--file-batch-size <n> | JSON-only bounded loading — one prepared runner per client-aligned physical batch. |
--evaluation-date | Pin preprocessing and rule evaluation to a date (YYYY-MM-DD). |
--reference-manifest <path> | Explicit reference bundle; required in production when selected rules use reference data. |
--reference-as-of | Publication / freshness policy date; requires --reference-manifest. |
--reference-legacy-auto-load | Test/debug compatibility loader; rejected in production. |
--kpi-report-dir <dir> | Write KPI and performance summaries in one safe run directory. |
--performance-audit | off / summary / detailed, plus per-stage threshold flags. |
--split-by / --aging / --payer | Grouping dimensions, aging buckets, payer-code filter. |
--tenant-config / --provider | Tenant routing configuration and provider override. |
--rule / --domain / --phase | Rule selection filters (repeatable or comma-separated). |
--include-claim-id | Emit raw claim IDs into reports (reintroduces PHI; requires a report directory). |
--feedback-token-key-file | Publish tenant-bound claim/revision identities under protected-feedback/. |
--auth-config / --auth-token / --require-auth | Execution auth gate; fails closed when required. |
Where each launch option is captured in this console
The screens collect these values because the console launches the runner with them — the CLI flags are the source of truth, the fields are the same options.
| CLI option | Captured in |
|---|---|
<rule_file> (rule pack) | Rules screen — rule pack selection |
--claims <dir> / --claim <file> | Data Source screen — source preset |
--mode, --performance-audit | Batch Run screen — launch summary |
--profile, --evaluation-date, --tenant-config | Settings — Execution |
--reference-manifest, --reference-as-of | Settings — Reference data |
--include-claim-id, --performance-audit-fail-on-warning | Settings — Reporting & artifacts |
--require-auth, --auth-config | Settings — Auth |
test-case --record, --tested-by | Manual Test Cases screen — scripted case runs |
--kpi-report-dir | Artifacts screen — immutable run report tree |
The console never shells out to the CLI binary — it calls the same shared manual-test runner library — so these fields stay equivalent to the flags rather than parsing terminal output.
User guide
- Quick Start — install, build, parse, and run a first rule.
- Testing Rules —
klaim test-case, single-claim debug traces, focused--rule/--domain/--phaseruns. - Batch Processing & KPI Summary — claims directory structure,
--file-batch-size, report contract. - Log Viewer & Debugging Workflow — capturing
tools/logs.jsonland reading it. - CLI Reference — every flag this console's screens map to (see the tables above).
Full text: docs/guides/02-user-guide.md.
Manual rule testing guide
- Test-case definition — the YAML shape for one scripted manual case.
- Manual ledger — the
ledger.csvaudit trail every run appends to. - Structured single-case runner —
klaim test-caseand its immutable per-run artifacts. - Local HTML testing tool — the design this console (Manual Test Cases screen) implements.
Full text: docs/guides/11-manual-rule-testing-guide.md.
Operations guide
- Execution Sequence — compilation, planning, evaluation, and reduction order.
- Rule Activation Index — safe candidate pre-filtering and runtime counters.
- Pre-Processing Engine — discovery, deduplication, publication, and the ledger.
- Runtime Performance Audit — collection levels, thresholds, outputs, and gates.
Full text: docs/guides/24-operations.md.
Related skills
- launch-rule-engine — build, verify the reference bundle, run the production performance audit over the test corpus.
- execute-manual-test-case — run one rule's scripted cases and the activation-parity test (powers the Manual Test Cases screen).
- analyze-rule-engine-outcome — value-level replica analysis of a run's findings (which ZIPs, payers, cities fired a rule).
Keyboard shortcuts
About this console
The configure and execute flows are live: rule packs load through /api/rule-packs, sources validate through /api/sources/inspect, corpus and uploaded-claim runs use /api/test-runs (/api/test-runs/upload for a file dropped on the Manual Test Cases screen), the Claim File Run screen parses and executes a one-or-many-claim file through /api/claim-files/parse and /api/claim-files/run, the Claim Inspector searches a source through /api/claims/index and reads one claim through /api/claims/detail, and manual cases remain on /api/cases. X12 EDI uploads are rejected with the engine's own NORMALIZATION_EDI_UNSUPPORTED — the 837 normalizer is not implemented yet. The server calls shared Rust loader, planner, reference, source, runtime, and reducer crates directly; it never shells out to the CLI. The Artifacts, Log Viewer, and Performance & KPI screens read every execution's published report, result record, and captured engine log through /api/executions; each report file can be read structured or raw and downloaded, alone or as one zip of the run.