Verify Runtime Behavior
After changing data-flow code, verify it works at runtime — not just that it compiles.
When to Use
- Modified files in
**/api/**or**/shared/api/** - Changed dual-write, shadow-read, or mutation logic
- Fixed a data-flow bug and need evidence it's resolved
Prerequisites
The Vite dev server must be running (npm run dev) for logs to be captured. devLog() POSTs to /__dev/log which the Vite plugin writes to .logs/dev-*.jsonl. Without the server, no entries are recorded.
Verification Flow
digraph verify {
"Code change made" -> "Type-check passes?";
"Type-check passes?" -> "Fix types" [label="no"];
"Type-check passes?" -> "Tests pass?" [label="yes"];
"Tests pass?" -> "Fix tests" [label="no"];
"Tests pass?" -> "Dev server running?" [label="yes"];
"Dev server running?" -> "npm run dev" [label="no"];
"Dev server running?" -> "Trigger action in browser" [label="yes"];
"npm run dev" -> "Trigger action in browser";
"Trigger action in browser" -> "Run devlog:check";
"Run devlog:check" -> "Errors found?";
"Errors found?" -> "Diagnose from logs" [label="yes"];
"Diagnose from logs" -> "Code change made";
"Errors found?" -> "Warnings present?" [label="no"];
"Warnings present?" -> "Review mismatches" [label="yes"];
"Warnings present?" -> "Verified" [label="no"];
"Review mismatches" -> "Verified";
}Commands
npm run type-check # Static types
npm run test:run # Unit tests
npm run devlog:check # Runtime verification (exit 1 on errors, exit 0 on warnings)
npm run devlog:errors # Show warnings + errors
npm run devlog # Show recent events
npm run devlog:trace ID # Trace one action by correlationIdQuick HTTP checks (dev server running)
curl localhost:PORT/__dev/logs # JSON array of recent entries
curl localhost:PORT/__dev/logs?limit=5 # Last 5 entries
curl localhost:PORT/__dev/logs/path # Current log file pathWhat to Check
| Category | Good Signal | Bad Signal |
|---|---|---|
dual-write | write-success for your entity | write-error or unexpected write-skipped |
shadow-read | compare-match | compare-mismatch with missing IDs |
| Any | Events present for your change | Zero events (code path not hit) |
Note: devlog:check exits 0 on warnings (mismatches), exits 1 only on errors. Always review warnings — shadow-read mismatches may indicate backfill gaps.Red Flags
- "It compiles, so it works" — Dual-write can compile and silently fail at runtime.
- "No errors in the log" — Check that events WERE logged. Zero events means the code path wasn't exercised.
- "I can't start the dev server" — Note the verification gap. Run
devlog:checkafter available test runs.
Log Format
Files: .logs/dev-*.jsonl — one JSON object per line.
Each entry has: timestamp, category, event, level (info/warn/error), correlationId, optional data and duration.
Grep patterns:
- All errors:
grep '"level":"error"'.logs/dev-*.jsonl - Dual-write issues:
grep '"category":"dual-write"'.logs/dev-*.jsonl - Mismatches:
grep '"event":"compare-mismatch"'.logs/dev-*.jsonl