Skip to content

feat(cli): Add trace divergence diff command (chronos diff) #18

Description

@sx4im

Problem Statement

When debugging why seed A passed and seed B failed (or checking whether an architectural refactor altered an execution path), developers currently have to manually compare multi-megabyte trace JSONs or parse events by eye. A dedicated CLI diff command is needed to locate the exact first point of divergence between two failure capsules or traces.

Desired Implementation

  • Implementation File: packages/cli/src/diff.ts
    • Export diffCommand(capsulePathA: string, capsulePathB: string): Promise<DiffResult>
    • Parse and validate both capsules using readCapsule (with path confinement via resolveCapsulePath).
    • Compare the event streams sequentially: compare virtual timestamp t, sequence counter seq, event kind, participating nodes (nodeId / from / to), and payload summary.
  • CLI Dispatcher Integration: packages/cli/src/index.ts
    • Register chronos diff <capsule-a> <capsule-b> in runCommand and buildHelpText.
  • Unit Tests: packages/cli/test/diff.test.ts
    • Test identical traces, early divergence, length mismatches, and untrusted path rejection.

Acceptance Criteria

  • Path Confinement (Negative Case): Refuses paths outside allowed project directories with CapsulePathRefused (closing the arbitrary file read disclosure path per audit B4).
  • Malformed Capsule (Negative Case): Exits with code 2 on non-existent, unreadable, or schema-invalid JSON capsule files.
  • Identical Traces (Positive Case): Exits with code 0 and outputs ✔ Traces are bit-for-bit identical (N events compared).
  • Divergent Traces (Positive Case): Exits with code 1 and prints the exact first divergent step index, timestamp t, event kinds, and field-level diff (e.g. Event #14 (t=45ms): capsule A sent 'msg-1' to node-2, but capsule B sent 'msg-2' to node-3).
  • Zero Dependencies: Pure Node.js built-ins; no external diff libraries.

Verification Commands

# Run the CLI test suite
pnpm --filter @sx4im/chronos-cli test

# Verify monorepo typecheck and linting
pnpm typecheck && pnpm lint

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions