Summary

When debugging AllSource-backed applications (e.g., Longhand desktop app), there is no way to inspect the raw event data stored in WAL and Parquet files from developer tools like Claude Code. This blocks efficient diagnosis of data corruption, projection mismatches, and stale state issues.

What's needed

1. Local parquet/WAL reader CLI or library

A way to read AllSource storage files directly from disk:

~/Library/Application Support/Longhand/allsource/
├── storage/   # 139 parquet files (events-YYYYMMDD-*.parquet)
└── wal/       # wal-0000000000000000.log

Requirements:

• Read parquet files and output events as JSON (filtered by entity_id, event_type, time range)
• Read WAL log and output uncommitted events
• Available as a CLI tool (allsource-inspect or similar) that can be run without starting a full Core server
• Ideally a Rust binary in crates/ or tooling/ that links against allsource-core directly

Example usage:

allsource-inspect --data-dir ~/Library/Application\ Support/Longhand/allsource \
  --entity-id "workflow:16c13458-..." \
  --event-type "workflow_run.*" \
  --format json

2. MCP server local/embedded mode

The existing mcp-server-elixir connects to a remote Core server over HTTP/WebSocket. For local desktop apps using allsource-core embedded, we need:

• Local mode: MCP server that reads directly from the WAL + parquet files on disk (no network Core instance required)
• Configuration: Point it at a data directory, it opens the store read-only
• Tools exposed: The existing MCP tools are excellent for debugging — quick_stats, sample_events, query_events, get_snapshot, reconstruct_state, analyze_changes, event_timeline, explain_entity — these are exactly what's needed

Option A: Add an embedded mode to mcp-server-elixir that uses the NIF to open the store directly
Option B: Create a lightweight Rust MCP server (stdio transport) that wraps allsource-core embedded — simpler for local dev, can be added to Claude Code's MCP config

3. Claude Code skills for AllSource debugging

Skills (.claude/skills/) that encode best practices for debugging AllSource-backed apps:

• allsource-debug: How to inspect projections, query events by entity, trace event replay, diagnose stale/corrupt projection state
• allsource-data-access: Patterns for reading WAL vs parquet, understanding the storage layout, interpreting event schemas
• allsource-mcp-setup: How to configure the MCP server for local debugging in Claude Code's settings

4. Documentation

• Storage format guide: Document the parquet schema (columns, partitioning), WAL format, and how events flow from ingest → WAL → parquet
• Projection debugging guide: How to verify projection state matches raw events, how to detect missed events or replay gaps
• Local development guide: How to inspect AllSource data without a running application (for post-mortem debugging)

Context

This came up while debugging the Longhand desktop app where:

• Workflow run projections showed runsCount: 0 for a definition with 5 actual runs across 4 execution workflow IDs
• The fix required adding a definition_id field to the WorkflowRunEvent::Started event and a by_definition secondary index to the projection
• Diagnosing this required reading the projection debug output from the UI — there was no way to directly query the underlying events to verify the projection state vs raw data
• pyarrow is not available by default, and installing dependencies during debugging sessions is disruptive

Priority

High for developer experience. AllSource's strength is immutable event history — but that history is opaque without tooling to read it.