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
Verification Commands
# Run the CLI test suite
pnpm --filter @sx4im/chronos-cli test
# Verify monorepo typecheck and linting
pnpm typecheck && pnpm lint
Problem Statement
When debugging why seed
Apassed and seedBfailed (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
packages/cli/src/diff.tsdiffCommand(capsulePathA: string, capsulePathB: string): Promise<DiffResult>readCapsule(with path confinement viaresolveCapsulePath).t, sequence counterseq, eventkind, participating nodes (nodeId/from/to), and payloadsummary.packages/cli/src/index.tschronos diff <capsule-a> <capsule-b>inrunCommandandbuildHelpText.packages/cli/test/diff.test.tsAcceptance Criteria
CapsulePathRefused(closing the arbitrary file read disclosure path per audit B4).2on non-existent, unreadable, or schema-invalid JSON capsule files.0and outputs✔ Traces are bit-for-bit identical (N events compared).1and prints the exact first divergent step index, timestampt, 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).Verification Commands