fix(search): complete @MrBeldum's #88 — local-day dates, tolerant timestamps, documented semantics

README.md

@@ -182,13 +182,23 @@ project:name     Filter by project path/name
 model:opus       Filter by model (partial match)
 tool:Bash        Sessions using specific tool
 file:path        Filter by file path
-before:date      Sessions before date (YYYY-MM-DD)
-after:date       Sessions after date
+before:date      Turns before date, excluding that date itself (YYYY-MM-DD)
+after:date       Turns from the start of date, including that date
 has:error        Sessions with errors
 has:subagent     Sessions with subagent usage
 "exact phrase"   Exact phrase match
 ```
 
+The two date filters are not symmetric, which is worth knowing before reading
+a result count. `before:` stops at the named date without reaching it, so
+`after:2026-01-01 before:2026-01-31` covers the 1st through the 30th and not
+the 31st. To include a day, name the one after it: `before:2026-02-01`.
+
+A written-out date is a UTC calendar day, because that is the zone turns are
+stamped in. The relative forms — `today`, `yesterday`, `week`, `month` — are
+resolved on your own calendar instead, so `after:today` means the day it is
+where you are.
+
 Examples:
 ```bash
 ccvault search "debugging the API endpoint"

cmd/ccvault/main.go

@@ -367,8 +367,8 @@ Use --json for machine-readable output.`,
 				"model:<name>":     "Filter by model",
 				"tool:<name>":      "Filter by tool used",
 				"source:<name>":    "Filter by source",
-				"after:<date>":     "Sessions after date",
-				"before:<date>":    "Sessions before date",
+				"after:<date>":     "From the start of date, including that date",
+				"before:<date>":    "Before date, excluding that date itself",
 				"\"exact phrase\"": "Exact phrase match",
 			},
 		}
@@ -645,9 +645,17 @@ Supports Gmail-like query syntax:
   project:name     Filter by project
   model:opus       Filter by model
   tool:Bash        Sessions using specific tool
-  before:date      Date filters
-  after:date
-  "exact phrase"   Exact match`,
+  before:date      Before date, excluding that date itself
+  after:date       From the start of date, including that date
+  "exact phrase"   Exact match
+
+Both date bounds land on midnight starting the day they name, so
+"after:2026-01-01 before:2026-01-31" covers the 1st through the 30th. Name
+the day after to include the last one: "before:2026-02-01".
+
+A written-out date (2026-01-15, 2026/01/15, "Jan 15, 2026") is a UTC calendar
+day, matching how turns are stamped. today, yesterday, week and month are
+resolved on this machine's own calendar instead.`,
 	Args: cobra.MinimumNArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		queryStr := strings.Join(args, " ")

internal/search/datefilter_test.go

@@ -28,6 +28,37 @@ type windowFixture struct {
 // what the date filter under test asks for.
 const windowFirstDay = "2026-09-28"
 
+// boundaryZone is the zone the bare dates in a query are parsed in while the
+// boundary test runs.
+//
+// Pinned, because a bare before:/after: date is parsed in the caller's zone
+// while the fixtures below stamp their turns in UTC — so left to the machine's
+// own zone, these assertions would be answering a slightly different question
+// on every developer's laptop and in CI.
+//
+// Deliberately not UTC. Pinning to UTC would make the two sides agree by
+// construction and the test would stop saying anything about the zone at all;
+// an offset is what makes it assert that a locally-parsed bound and a
+// UTC-stamped row still land on the same side of a boundary. A half-hour
+// offset rather than a whole-hour one because it also catches an arithmetic
+// slip that rounds to the hour.
+//
+// A fixed offset rather than a named zone so the test does not depend on the
+// machine carrying a zoneinfo database.
+var boundaryZone = time.FixedZone("UTC+05:30", 5*60*60+30*60)
+
+// pinLocalZone fixes time.Local for the duration of one test.
+//
+// Assigning it is safe here: nothing in this package runs its tests in
+// parallel, and the original is put back before the next test starts.
+func pinLocalZone(t *testing.T, loc *time.Location) {
+	t.Helper()
+
+	original := time.Local
+	time.Local = loc
+	t.Cleanup(func() { time.Local = original })
+}
+
 func setupWindowFixture(t *testing.T) windowFixture {
 	t.Helper()
 
@@ -212,6 +243,8 @@ func TestSearch_DateFilterScopesItsTermsToThePeriodColumn(t *testing.T) {
 // month and one at the first instant of the next belong to different tokens
 // but can belong to the same window.
 func TestSearch_DateFilterReturnsTheSameRowsAtPeriodBoundaries(t *testing.T) {
+	pinLocalZone(t, boundaryZone)
+
 	database, err := db.Open(t.TempDir())
 	if err != nil {
 		t.Fatalf("open db: %v", err)
@@ -333,11 +366,11 @@ func TestSearch_DateFilterReturnsTheSameRowsAtPeriodBoundaries(t *testing.T) {
 // exactly as it did before the period column existed. Dropping it inside the
 // index would be a wrong answer rather than a slow one.
 //
-// Asserted on the index rather than through Search, because Search cannot
-// return such a row at all: scanning turns.timestamp into a time.Time fails
-// for text no date format parses, and the whole query errors with it. That is
-// pre-existing and left alone here — and it is also why the sentinel has to be
-// checked where it lives.
+// Asserted on the index, because that is where the sentinel lives, and then
+// through Search, because the row now survives the trip back out. Scanning
+// turns.timestamp straight into a time.Time used to fail for text no date
+// format parses and take the whole query down with it — one bad row made every
+// search that reached it an error, which is issue #85.
 func TestSearch_DateFilterKeepsAnUnreadableTimestamp(t *testing.T) {
 	database, err := db.Open(t.TempDir())
 	if err != nil {
@@ -371,11 +404,33 @@ func TestSearch_DateFilterKeepsAnUnreadableTimestamp(t *testing.T) {
 		t.Fatalf("insert undated turn: %v", err)
 	}
 
-	filtered, _ := matchExprs(t, New(database.DB), Parse("unreadableneedle after:2026-09-30"))
+	searcher := New(database.DB)
+	filtered, _ := matchExprs(t, searcher, Parse("unreadableneedle after:2026-09-30"))
 
 	if got := matchCount(t, database, "turns_fts", filtered); got != 2 {
 		t.Errorf("the date-filtered expression matches %d turns, want both — the dated one, and the one whose period the column could not read", got)
 	}
+
+	// And the search completes rather than erroring on the way past the row.
+	// An unreadable date reads back as the zero time, which is the honest
+	// answer for a timestamp nothing can parse; losing every other result to it
+	// is not.
+	results, err := searcher.Search(Parse("unreadableneedle after:2026-09-30"), 50)
+	if err != nil {
+		t.Fatalf("search across the row with the unreadable timestamp: %v", err)
+	}
+	var undated *Result
+	for i := range results {
+		if results[i].Turn.ID == "turn-undated" {
+			undated = &results[i]
+		}
+	}
+	if undated == nil {
+		t.Fatalf("search returned %v, want the row with the unreadable timestamp among them", resultIDs(results))
+	}
+	if !undated.Turn.Timestamp.IsZero() {
+		t.Errorf("the unreadable timestamp read back as %v, want the zero time", undated.Turn.Timestamp)
+	}
 }
 
 // TestSearch_PayloadAttributionDrivesFromTheTurn pins the query plan of the two

internal/search/query.go

@@ -16,8 +16,8 @@ type Query struct {
 	Model    string    // model: filter
 	Tool     string    // tool: filter
 	File     string    // file: filter
-	Before   time.Time // before: filter
-	After    time.Time // after: filter
+	Before   time.Time // before: filter (upper bound, exclusive; a bare date is local midnight of that day)
+	After    time.Time // after: filter (lower bound, exclusive; a bare date is local midnight of that day)
 	HasError bool      // has:error filter
 	HasAgent bool      // has:subagent filter
 	Source   string    // source: filter
@@ -67,8 +67,10 @@ func Parse(input string) *Query {
 	return q
 }
 
-// parseDate parses a date string in various formats
+// parseDate parses a date string as the caller's local midnight for that day.
+// Relative tokens (today, yesterday, …) use the local calendar, not UTC Truncate.
 func parseDate(s string) time.Time {
+	loc := time.Local
 	formats := []string{
 		"2006-01-02",
 		"2006/01/02",
@@ -78,21 +80,24 @@ func parseDate(s string) time.Time {
 	}
 
 	for _, format := range formats {
-		if t, err := time.Parse(format, s); err == nil {
+		if t, err := time.ParseInLocation(format, s, loc); err == nil {
 			return t
 		}
 	}
 
-	// Try relative dates
+	now := time.Now().In(loc)
+	y, m, d := now.Date()
+	today := time.Date(y, m, d, 0, 0, 0, 0, loc)
+
 	switch strings.ToLower(s) {
 	case "today":
-		return time.Now().Truncate(24 * time.Hour)
+		return today
 	case "yesterday":
-		return time.Now().Truncate(24 * time.Hour).Add(-24 * time.Hour)
+		return today.AddDate(0, 0, -1)
 	case "week", "thisweek":
-		return time.Now().Truncate(24 * time.Hour).Add(-7 * 24 * time.Hour)
+		return today.AddDate(0, 0, -7)
 	case "month", "thismonth":
-		return time.Now().Truncate(24 * time.Hour).Add(-30 * 24 * time.Hour)
+		return today.AddDate(0, 0, -30)
 	}
 
 	return time.Time{}

internal/search/search.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"regexp"
 	"strings"
+	"time"
 
 	"github.com/2389-research/ccvault/pkg/models"
 )
@@ -76,11 +77,12 @@ func (s *Searcher) Search(q *Query, limit int) ([]Result, error) {
 		var content sql.NullString
 		var parentSessionID sql.NullString
 		var matchedTool, matchedPayload sql.NullString
+		var rawTS any
 		err := rows.Scan(
 			&r.Turn.ID,
 			&r.SessionID,
 			&r.Turn.Type,
-			&r.Turn.Timestamp,
+			&rawTS,
 			&r.Turn.Ordinal,
 			&content,
 			&r.ProjectPath,
@@ -93,6 +95,7 @@ func (s *Searcher) Search(q *Query, limit int) ([]Result, error) {
 		if err != nil {
 			return nil, fmt.Errorf("scan result: %w", err)
 		}
+		r.Turn.Timestamp = coerceTimestamp(rawTS)
 		r.ParentSessionID = parentSessionID.String
 		if content.Valid {
 			r.Turn.Content = content.String
@@ -444,6 +447,44 @@ func (s *Searcher) turnDate(query string) (string, error) {
 	return date.String, nil
 }
 
+// coerceTimestamp turns a driver value into a time.Time without failing the
+// whole Search when one row holds an unparseable timestamp string (#85).
+func coerceTimestamp(v any) time.Time {
+	switch t := v.(type) {
+	case nil:
+		return time.Time{}
+	case time.Time:
+		return t
+	case string:
+		return parseStoredTimestamp(t)
+	case []byte:
+		return parseStoredTimestamp(string(t))
+	default:
+		return time.Time{}
+	}
+}
+
+func parseStoredTimestamp(s string) time.Time {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return time.Time{}
+	}
+	formats := []string{
+		time.RFC3339Nano,
+		time.RFC3339,
+		"2006-01-02 15:04:05.999999999 -0700 MST", // time.Time.String()
+		"2006-01-02 15:04:05.999999999 -0700",
+		"2006-01-02 15:04:05",
+		"2006-01-02",
+	}
+	for _, f := range formats {
+		if t, err := time.Parse(f, s); err == nil {
+			return t
+		}
+	}
+	return time.Time{}
+}
+
 // makeSnippet creates a snippet from content with the search term highlighted
 func makeSnippet(content, searchTerm string, maxLen int) string {
 	if content == "" {