Artifact [a69ab5dba7]

Artifact a69ab5dba734bd7c221773376ab8c59a766402be2d8a03b1ff1a9a3ba08c556c:

• File types.go — part of check-in [168e20fc91] at 2026-07-19 16:30:58 on branch trunk — fix: make Timeline pagination cursor an exact total order (#62)

  * fix: make Timeline pagination cursor an exact total order

  #54 (merged as 95cbbb7) split Repo.Timeline into a repository-wide enumeration and Repo.Ancestry, the original first-parent walk under an honest name. Its pagination cursor predicate used a tolerance window around the caller-supplied Before/After pair to work around a lossy julian<->time.Time round trip:

  mtime < (C - eps) OR (mtime <= (C + eps) AND rid < After)

  This reintroduces exactly the defect the composite cursor existed to prevent, and makes it worse: rows within eps of the boundary that are not real ties get filtered by rid instead of tie-broken by it, which can skip a row, duplicate another, or fail to advance the cursor at all — unlike canonical fossil's own bare-timestamp slop, which repeats rows but still advances. A pagination test using only exact-tie and one-hour-apart fixtures could not exercise the 0 < delta < eps range where the defect lives, so it stayed green.

  Fix: make the predicate an exact total order, with rid as a true tie-break only at exact mtime equality:

  mtime < C OR (mtime = C AND rid < After)

  and stop deriving C from a time.Time altogether. TimelineOpts.After is now an opaque Cursor (internal/fsltype.Cursor, re-exported as libfossil.Cursor): obtained only from a LogEntry the library already produced, carrying the exact float64 mtime read off that row rather than one reconstructed from a rounded timestamp. A cursor built from parts can silently drift from the row it claims to follow; a cursor that can only ever be handed back cannot.

  That exactness depends on the row's scanned mtime being faithful to begin with, which surfaced a second bug: under the ncruces/WASM sqlite driver, event.mtime scans as a time.Time via the driver's own internal REAL conversion, carrying ~13us of noise that db.ScanJulianDay's time.Time branch then truncated (via UnixMilli()) into a full missed millisecond — independent of and in addition to the JulianToTime truncation bug #54 already fixed on the read-back side. Fixed db.timeToJulian to round to the nearest millisecond, the same class of fix, at the point where the driver-specific noise actually enters.

  Also tightened the regression coverage: - Pagination tests now use a fixed loop bound of exactly ceil(n/pageSize) pages rather than an open "while non-empty" loop, so a non-advancing cursor fails the test immediately instead of hanging it. - Added a sub-millisecond-boundary fixture (events 3ms apart, well inside the old epsilon window) with rid order deliberately decoupled from mtime order — a monotonic fixture cannot expose this class of bug, since rid and mtime need not move together in general (backdated commits, imports). - TestJulianRoundTrip now asserts exact equality for values originating from TimeToJulian instead of a *1ms tolerance, which would have passed under both the old truncating JulianToTime and the current rounding one and so was not a regression guard for that fix.

  No change to Ancestry, event-type filtering, NULL tolerance, or either loop bound; all were already correct.

  * fix: assert pagination termination; mark Cursor change breaking

  Both pagination tests (the pre-existing ones and the sub-millisecond regression) ran exactly ceil(n/pageSize) pages and asserted each event appeared once, but neither ever called Timeline one more time to confirm the next page comes back empty. The headline symptom of the epsilon-cursor defect these tests exist to catch was non-termination — a caller paginating until empty never stops — and that specific failure mode was going unguarded: a cursor that enumerates every row correctly but never signals exhaustion would have passed all four tests as they stood.

  Added one more Timeline call after the last expected page in all four tests, asserting it returns zero entries. Verified this is not vacuous: reverted the tie-break to <= (non-strict) and confirmed the existing per-event count checks catch it; separately, made Timeline phantom-return one row only on an already-exhausted call (isolated from the real per-page counts, which stayed correct in that experiment) and confirmed only the new final-page assertion fails — proving it exercises a real, non-redundant path, not one already covered by the count checks. Both experiments reverted before commit.

  Also corrected the CHANGELOG bullet describing the Cursor redesign: it described the new Cursor type but never stated that TimelineOpts.Before (time.Time) and TimelineOpts.After (FslID) were deleted outright, not deprecated. A reader diffing releases would have read it as an addition rather than a second compile-breaking change on top of #54. (user: [email protected], size: 2008) [annotate] [blame] [check-ins using]

package libfossil

import "github.com/danmestas/libfossil/internal/fsltype"

// FslID is a row-id in the blob table (content-addressed artifacts).
type FslID = fsltype.FslID

// FslSize represents a blob size; negative values indicate phantom blobs.
type FslSize = fsltype.FslSize

const (
	PhantomSize         FslSize = fsltype.PhantomSize
	FossilApplicationID int32   = fsltype.FossilApplicationID
)

// EventKind is the type discriminator on a Timeline entry: one of the
// single-letter codes fossil assigns per event.type row. The zero value
// means "all kinds" — the default Timeline uses when no Type is given.
type EventKind = fsltype.EventKind

const (
	// EventKindCheckin is a check-in ('ci').
	EventKindCheckin EventKind = fsltype.EventKindCheckin
	// EventKindTechnote is a technote / event artifact ('e').
	EventKindTechnote EventKind = fsltype.EventKindTechnote
	// EventKindForum is a forum post ('f').
	EventKindForum EventKind = fsltype.EventKindForum
	// EventKindTag is a tag/control artifact ('g').
	EventKindTag EventKind = fsltype.EventKindTag
	// EventKindTicket is a ticket change ('t').
	EventKindTicket EventKind = fsltype.EventKindTicket
	// EventKindWiki is a wiki page edit ('w').
	EventKindWiki EventKind = fsltype.EventKindWiki
)

// Cursor is an opaque pagination token for Timeline. Obtain one from a
// returned LogEntry's Cursor field and pass it back as the next
// TimelineOpts.After to resume enumeration immediately after that entry.
// The zero Cursor means "start from the newest event".
//
// Cursor's representation is deliberately hidden: it cannot be
// constructed from a timestamp and a rid by calling code, only obtained
// from a LogEntry the library already produced. See fsltype.Cursor's doc
// comment for why — a hand-built cursor derived from a rounded time.Time
// is not guaranteed to match the row it claims to follow exactly, which
// is what silently reintroduces skipped or duplicated rows at a page
// boundary.
type Cursor = fsltype.Cursor