beads/internal/storage/batch.go
Steve Yegge 33bf6d0c02 fix(import): equal-timestamp upsert keeps the local row; report what import changed (bd-hj85c)
Two gaps remained after the bd-pkim8 stale guard (wyvern wy-78o incident):

1. Equal-timestamp clobber: the guarded upsert accepted VALUES(updated_at)
   >= updated_at, so an incoming row tying the stored second-granularity
   updated_at rewrote every column — an import row with empty notes wiped
   freshly-set local notes. The accept condition is now strictly newer (>);
   ties keep every stored column while the row's aux data (labels,
   comments, deps — which never bump updated_at) still merges. The
   pre-filter compares at second granularity so a sub-second JSONL
   timestamp can't promote a tie to "newer", and re-importing an identical
   snapshot stays idempotent.

2. Silent local-state changes: import reported only created/skipped
   counts. It now lists which existing issues it rewrote with a
   field-level summary (updated_issues, e.g. "status closed → open") and
   which equal-timestamp conflicting rows kept local state
   (tie_kept_local_ids), in both human and --json output. Updates the
   in-txn guard rejects (raced local writes) drop out of the report.

Import commits also tolerate "nothing to commit", since a tie-kept import
can be a working-set no-op.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-12 17:58:40 -04:00

56 lines
3 KiB
Go

// Package storage defines the interface for issue storage backends.
package storage
// OrphanHandling specifies how to handle issues with missing parent references.
type OrphanHandling string
const (
// OrphanStrict fails import on missing parent (safest)
OrphanStrict OrphanHandling = "strict"
// OrphanResurrect auto-resurrects missing parents from database history
OrphanResurrect OrphanHandling = "resurrect"
// OrphanSkip skips orphaned issues with warning
OrphanSkip OrphanHandling = "skip"
// OrphanAllow imports orphans without validation (default, works around bugs)
OrphanAllow OrphanHandling = "allow"
)
// BatchCreateOptions contains options for batch issue creation.
// This is a backend-agnostic type that can be used by any storage implementation.
type BatchCreateOptions struct {
// OrphanHandling specifies how to handle issues with missing parent references
OrphanHandling OrphanHandling
// SkipPrefixValidation skips prefix validation for existing IDs (used during import)
SkipPrefixValidation bool
// ConflictSkip makes batch creation insert-if-new instead of UPSERT: an
// issue whose ID already exists is left untouched rather than overwritten.
// Used only by the auto-import upgrade-recovery fallback (GH#3955), so
// that if the emptiness guard in maybeAutoImportJSONL ever regresses
// again (cf. PR #3630), auto-import degrades to a harmless no-op instead
// of clobbering live rows. Explicit `bd import` keeps UPSERT semantics.
ConflictSkip bool
// RejectStaleUpserts makes the issue-row UPSERT conditional on updated_at:
// the incoming row only rewrites the stored columns when it is strictly
// newer. A stored row that is strictly newer is rejected outright
// (OnStaleRejected fires, aux data skipped); an equal-timestamp row keeps
// every stored column but still merges its aux data — updated_at has
// second granularity, so a tie may be two distinct same-second updates
// and the local row wins it (bd-hj85c). This is the transactional half
// of the import stale guard (bd-pkim8): cmd/bd's filterStaleImportIssues
// reads local updated_at before the batch write, so a local update
// committing in between would otherwise be silently overwritten (the
// PR 4204 race). Set by `bd import` unless --allow-stale; create paths
// leave it false.
RejectStaleUpserts bool
// SkipDependencyValidationErrors skips dependency validation failures that
// legacy imports tolerated, such as cycles or self-dependencies.
SkipDependencyValidationErrors bool
// OnSkippedDependency records dependency edges skipped during batch create.
OnSkippedDependency func(issueID, dependsOnID, reason string)
// OnStaleRejected records issues whose row the RejectStaleUpserts guard
// kept (stored row strictly newer than the incoming one). Rejected issues
// also skip label/comment/dependency persistence, so callers can count
// them as skipped rather than created. May fire more than once per issue
// if the enclosing transaction retries; callers should dedup by ID.
OnStaleRejected func(issueID string)
}