idempotency

type BeginResult struct {
	// Record is the current record after TryBegin (either existing or newly created).
	Record Record `json:"record"`
	// Fresh indicates whether the caller acquired a new lease (should do work).
	Fresh bool `json:"fresh"`
}

type Clock interface {
	Now()
}

type KeyParts struct {
	Version string `json:"version"`
	Tenant  string `json:"tenant"`
	Scope   string `json:"scope"`
	Hash    string `json:"hash"` // lowercase hex sha256
}

type MemoryStore struct {
	// contains filtered or unexported fields
}

type Options struct {
}

type Record struct {
	Key string `json:"key"`

	State State `json:"state"`

	// OwnerToken is set when in_progress and must match to Complete/Fail/Touch.
	OwnerToken string `json:"owner_token,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	ExpiresAt time.Time `json:"expires_at"`

	// Result (for complete)
	ResultHash  string `json:"result_hash,omitempty"` // sha256 hex of ResultBytes
	ResultBytes []byte `json:"result_bytes,omitempty"`

	// Failure (for failed)
	ErrorCode string `json:"error_code,omitempty"`
	ErrorMsg  string `json:"error_msg,omitempty"`
}

type Store interface {
	// TryBegin attempts to acquire a lease for key. If key is complete, returns Fresh=false with the record.
	// If key is in_progress and not expired, returns Fresh=false with ErrConflict.
	// If key is expired, it is replaced and Fresh=true.
	TryBegin(ctx context.Context, key string, ttl time.Duration) (BeginResult, error)

	// Touch extends the lease if caller holds ownership (in_progress only).
	Touch(ctx context.Context, key string, ownerToken string, ttl time.Duration) (Record, error)

	// Complete marks the key complete (requires owner token).
	Complete(ctx context.Context, key string, ownerToken string, result []byte) (Record, error)

	// Fail marks the key failed (requires owner token).
	Fail(ctx context.Context, key string, ownerToken string, code string, msg string) (Record, error)

	// Get fetches record.
	Get(ctx context.Context, key string) (Record, bool, error)

	// Delete removes record (admin/debug).
	Delete(ctx context.Context, key string)

	// Sweep removes expired entries. Deterministic, no background goroutine.
	Sweep(ctx context.Context) (removed int, err error)
}