Fix Netdata query-wide anchors

Author: ktsaou

.agents/sow/SOW-status.md

@@ -4,16 +4,7 @@ Last updated: 2026-06-25
 
 ## Current
 
-- SOW-0124 - Netdata Query-Wide Anchor Regression: in-progress. Test-first
-  reproduction is active for the regression between the Netdata UI's single
-  ordered query-level anchor contract and the SDK Netdata wrappers' current
-  per-file anchor application plus after-the-fact timestamp merge. The current
-  surgical SDK repair plan is reviewer-verified READY TO IMPLEMENT by glm,
-  minimax, kimi, mimo, deepseek, and qwen after round-2 review. The plan keeps
-  the scalar anchor API and per-file batched retrieval, removes early
-  display-time timestamp mutation, makes non-tail backward anchors exclusive,
-  and makes final retention include the whole cross-file boundary timestamp
-  group.
+- None.
 
 ## Pending
 
@@ -50,6 +41,20 @@ Last updated: 2026-06-25
   decisions. Not executable until the user explicitly resumes it.
 ## Recently Closed Or Completed
 
+- SOW-0124 - Netdata Query-Wide Anchor Regression: completed. Rust and Go
+  Netdata SDK wrappers now preserve the current scalar `anchor` plus
+  `pagination.column = "timestamp"` wire contract while applying anchors
+  query-wide across selected journal files. The repair removes early
+  display-time timestamp mutation, makes non-tail backward anchors exclusive
+  for data-only and non-data-only requests, preserves per-file batched
+  retrieval plus global merge, retains the full equal-timestamp boundary group,
+  and fixes `items.after` / `items.before` reporting for boundary expansion.
+  Option 1B is documented as future reference only, not implemented. Validation
+  passed Rust library tests, full Go module tests, Python Netdata helper tests,
+  rebuilt Rust and Go wrappers, the shared anchor regression runner across
+  Rust/Go and four scenarios, whitespace checks, SOW audit, and second-round
+  read-only reviewer votes from glm, kimi, mimo, deepseek, and qwen all voting
+  `READY TO COMPLETE: YES`.
 - SOW-0121 - File-Backed Journalctl Full Parity And Ship Decision: completed
   after strict P0/P1/P2 reviewer-gate repair. Rust and Go portable
   `journalctl` now recognize the full official systemd v260.1 option/action

…-netdata-query-wide-anchor-regression.md …-netdata-query-wide-anchor-regression.md.agents/sow/current/SOW-0124-20260625-netdata-query-wide-anchor-regression.md renamed to .agents/sow/done/SOW-0124-20260625-netdata-query-wide-anchor-regression.md .agents/sow/current/SOW-0124-20260625-netdata-query-wide-anchor-regression.md renamed to .agents/sow/done/SOW-0124-20260625-netdata-query-wide-anchor-regression.md

@@ -404,6 +404,73 @@ Duplicate visible timestamps are made unique inside one query:
 - backward scans decrement a duplicate timestamp (`systemd-journal-execute.h:173-179`);
 - forward scans increment a duplicate timestamp (`systemd-journal-execute.h:282-288`).
 
+## Query-Wide Anchor Contract (SDK Netdata Boundary)
+
+SOW-0124 (2026-06-25) records the SDK Netdata function paging contract that
+matches the Netdata UI one-anchor assumption
+(`netdata/cloud-frontend @ b0f9c41cfc36`):
+
+- `anchor` is a microsecond timestamp scalar across all selected journal files,
+  not a per-file offset. The UI stores one scalar `anchorAfter` /
+  `anchorBefore` for the whole merged table and sends one scalar `anchor` on
+  every load-more and tail poll. Consumers must treat it as an ordered scalar;
+  they must not infer a per-file cursor from it.
+- The current wire shape exposes the anchor through `pagination.column =
+  "timestamp"`. In the SDK this value is the Explorer row realtime, before the
+  final same-file duplicate display adjustment: journal commit realtime unless
+  an older `_SOURCE_REALTIME_TIMESTAMP` is present and selected as the effective
+  row time. There is no separate hidden internal cursor or opaque page token in
+  this contract.
+- Forward paging is strict: rows must satisfy `realtime_usec > anchor` to be
+  eligible for the next page.
+- Non-tail backward paging is exclusive for all row queries, including
+  `data_only = true` and `data_only = false`. The SDK converts a non-tail
+  backward realtime anchor into an exclusive upper bound
+  (`anchor - 1` microsecond) before Explorer range filtering, then clears
+  the Explorer anchor slot. This prevents page 2 from re-fetching the
+  boundary group that page 1 already returned.
+- Tail paging is exclusive on the next microsecond (`anchor + 1`).
+- When a page boundary lands inside an equal scalar-timestamp group across
+  files, the SDK retains the full boundary group from the merged per-file
+  batches even though that may return more than the requested `last`. Returning
+  more rows in that case is preferred over making the scalar anchor skip rows
+  that share the boundary value, because the current wire contract cannot
+  represent a compound cursor.
+- The SDK sorts combined per-file rows by pre-deduplication
+  `row.realtime_usec` / `Row.RealtimeUsec` in the requested direction, with
+  deterministic tie-breakers by file path and cursor. The combined retention
+  uses the pre-deduplication timestamp at the `limit - 1` index as the
+  boundary. Backward pages retain every row whose timestamp is greater than or
+  equal to the boundary. Forward pages retain every row whose timestamp is less
+  than or equal to the boundary. Any same-file duplicate timestamp adjustment
+  runs only after that boundary retention, so the cross-file boundary group
+  stays intact.
+- Duplicate scalar timestamps across different journal files are preserved as
+  equal in the response. Cross-file equal timestamps are the anchor collisions
+  the scalar query-wide anchor must represent. Same-file duplicate timestamps
+  still receive the existing direction-specific increment/decrement display
+  adjustment as a small compatibility tweak inside one file only.
+- `items.after` / `items.before` semantics continue to indicate whether more
+  rows are available; a page that returns more than `last` rows because of
+  boundary-group retention must still report the correct remaining count
+  rather than a false "no more rows" signal.
+- The implementation keeps per-file batched retrieval and a global merge.
+  It does not switch to row-by-row k-way multi-file traversal. The user
+  measured row-by-row k-way multi-file traversal as significantly slower
+  than per-file batched query plus merge for many large sources, and the
+  per-file batched shape remains the SDK performance contract.
+- The implementation does not introduce a new request key or response
+  cursor token. The existing scalar `anchor` request shape and the existing
+  response columns remain the wire contract.
+
+The plugin's same-file duplicate display adjustment
+(`systemd-journal-execute.h:173-179`,
+`systemd-journal-execute.h:282-288`) is still preserved as a small cosmetic
+display tweak when the boundary group is fully retained. The change is only
+that the SDK no longer mutates row timestamps before range/anchor filtering,
+no longer mutates duplicate timestamps across files, and no longer relies on
+per-file exclusive anchor semantics for non-tail backward queries.
+
 ## File Selection And Traversal Order
 
 The plugin queries one journal file at a time. It never opens a multi-file

.agents/sow/specs/systemd-journal-plugin-facets.md

@@ -278,18 +278,17 @@ type ExplorerProgress struct {
 }
 
 type ExplorerControl struct {
-	deadline       *time.Time
-	cancellation   func() bool
-	progress       func(ExplorerProgress)
-	candidateRow   func(uint64) bool
-	adjustRealtime func(uint64) uint64
-	matchedRow     func(uint64, uint64) bool
-	sampling       *explorerSamplingState
-	progressEvery  time.Duration
-	started        time.Time
-	lastProgress   time.Time
-	nextCheckRows  uint64
-	stopReason     ExplorerStopReason
+	deadline      *time.Time
+	cancellation  func() bool
+	progress      func(ExplorerProgress)
+	candidateRow  func(uint64) bool
+	matchedRow    func(uint64, uint64) bool
+	sampling      *explorerSamplingState
+	progressEvery time.Duration
+	started       time.Time
+	lastProgress  time.Time
+	nextCheckRows uint64
+	stopReason    ExplorerStopReason
 }
 
 func NewExplorerControl() *ExplorerControl {
@@ -322,10 +321,6 @@ func (c *ExplorerControl) setCandidateRowCallback(callback func(uint64) bool) {
 	c.candidateRow = callback
 }
 
-func (c *ExplorerControl) setRealtimeAdjustCallback(callback func(uint64) uint64) {
-	c.adjustRealtime = callback
-}
-
 func (c *ExplorerControl) SetMatchedRowCallback(callback func(uint64, uint64) bool) {
 	c.matchedRow = callback
 }
@@ -394,13 +389,6 @@ func (c *ExplorerControl) emitMatchedRow(realtimeUsec, rowsMatched uint64) bool
 	return c != nil && c.matchedRow != nil && c.matchedRow(realtimeUsec, rowsMatched)
 }
 
-func (c *ExplorerControl) adjust(realtimeUsec uint64) uint64 {
-	if c != nil && c.adjustRealtime != nil {
-		return c.adjustRealtime(realtimeUsec)
-	}
-	return realtimeUsec
-}
-
 type explorerSamplingDecisionKind int
 
 const (
@@ -2122,9 +2110,7 @@ func handleRowValueClass(valueIndex int, acc *explorerAccumulator, rowID uint64,
 func acceptedEffectiveRealtime(query ExplorerQuery, scan rowScan, commitRealtime uint64, stats *ExplorerStats, control *ExplorerControl) (uint64, bool) {
 	effective := effectiveRealtimeFromScan(scan.timestamp, commitRealtime)
 	recordSourceRealtimeDelta(stats, scan.timestamp, commitRealtime)
-	if control != nil {
-		effective = control.adjust(effective)
-	}
+	_ = control
 	return effective, timestampInRange(query, effective) && !rowRejectedByFTS(query, scan)
 }